URI Operations

/**
 * Uniform Resource Identifier (URI) implementation following RFC 3986
 * Provides parsing, creation, and manipulation of URI components
 */
class URI {
  /** The scheme component (e.g., 'http', 'file', 'https') */
  readonly scheme: string;
  /** The authority component (e.g., 'www.example.com', 'localhost:8080') */
  readonly authority: string;
  /** The path component (e.g., '/some/path', '/file.txt') */
  readonly path: string;
  /** The query component (e.g., 'param=value&other=data') */
  readonly query: string;
  /** The fragment component (e.g., 'section', 'line-42') */
  readonly fragment: string;
  /** Filesystem path representation with platform-specific separators */
  readonly fsPath: string;

  /** Create new URI with modified components */
  with(change: {
    scheme?: string;
    authority?: string | null;
    path?: string | null;
    query?: string | null;
    fragment?: string | null;
  }): URI;

  /** Convert URI to string representation */
  toString(skipEncoding?: boolean): string;

  /** Convert URI to JSON-serializable object */
  toJSON(): UriComponents;
}

/**
 * Creates a new URI from a string representation
 * @param value - String representation of URI (e.g., 'http://example.com/path')
 * @param strict - Enable strict validation (default: false)
 * @returns Parsed URI instance
 */
static parse(value: string, strict?: boolean): URI;

import { URI } from "vscode-uri";

// Parse HTTP URI
const httpUri = URI.parse('https://code.visualstudio.com/docs/extensions/overview#frag');
console.log(httpUri.scheme);    // 'https'
console.log(httpUri.authority); // 'code.visualstudio.com'
console.log(httpUri.path);      // '/docs/extensions/overview'
console.log(httpUri.query);     // ''
console.log(httpUri.fragment);  // 'frag'

// Parse file URI
const fileUri = URI.parse('file:///c:/Users/name/file.txt');
console.log(fileUri.scheme);    // 'file'
console.log(fileUri.path);      // '/c:/Users/name/file.txt'

// Parse with query parameters
const queryUri = URI.parse('http://api.example.com/search?q=test&limit=10');
console.log(queryUri.query);    // 'q=test&limit=10'

/**
 * Creates a new URI from a file system path
 * Handles platform-specific path conventions and UNC paths
 * @param path - Filesystem path (e.g., '/usr/local/file.txt', 'C:\\Windows\\file.txt')
 * @returns URI with 'file' scheme
 */
static file(path: string): URI;

import { URI } from "vscode-uri";

// Unix-style path
const unixUri = URI.file('/usr/local/bin/code');
console.log(unixUri.toString()); // 'file:///usr/local/bin/code'
console.log(unixUri.fsPath);     // '/usr/local/bin/code'

// Windows-style path
const winUri = URI.file('C:\\Users\\name\\file.txt');
console.log(winUri.toString()); // 'file:///c%3A/Users/name/file.txt'

// UNC path
const uncUri = URI.file('\\\\server\\share\\file.txt');
console.log(uncUri.authority);  // 'server'
console.log(uncUri.path);       // '/share/file.txt'

// Paths with special characters
const specialUri = URI.file('/path with spaces/file#with-hash.txt');
console.log(specialUri.toString()); // Properly encoded URI

/**
 * Creates a new URI from component object with validation
 * @param components - Object containing URI components
 * @returns New URI instance
 */
static from(components: UriComponents): URI;

interface UriComponents {
  scheme: string;
  authority: string;
  path: string;
  query: string;
  fragment: string;
}

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

// Create HTTP URI from components
const httpUri = URI.from({
  scheme: 'https',
  authority: 'api.example.com',
  path: '/v1/users',
  query: 'limit=50',
  fragment: ''
});
console.log(httpUri.toString()); // 'https://api.example.com/v1/users?limit=50'

// Create file URI from components
const fileComponents: UriComponents = {
  scheme: 'file',
  authority: '',
  path: '/home/user/document.txt',
  query: '',
  fragment: ''
};
const fileUri = URI.from(fileComponents);

/**
 * Type guard to check if object is a URI instance
 * @param thing - Object to check
 * @returns True if object is URI instance
 */
static isUri(thing: any): thing is URI;

/**
 * Revive URI from serialized data with null/undefined handling
 * @param data - Serialized URI data or URI instance
 * @returns Revived URI instance or original value if null/undefined
 */
static revive(data: UriComponents | URI | undefined | null): URI | undefined | null;

/**
 * Create new URI with modified components
 * @param change - Object specifying which components to change
 * @returns New URI instance with modifications
 */
with(change: {
  scheme?: string;
  authority?: string | null;
  path?: string | null;
  query?: string | null;
  fragment?: string | null;
}): URI;

import { URI } from "vscode-uri";

const original = URI.parse('https://example.com/path?query=value');

// Change only the path
const withNewPath = original.with({ path: '/new/path' });
console.log(withNewPath.toString()); // 'https://example.com/new/path?query=value'

// Change multiple components
const modified = original.with({
  scheme: 'http',
  query: 'updated=true',
  fragment: 'section1'
});
console.log(modified.toString()); // 'http://example.com/path?updated=true#section1'

// Clear components by setting to null
const cleared = original.with({ query: null, fragment: null });
console.log(cleared.toString()); // 'https://example.com/path'

/**
 * Creates string representation of URI
 * @param skipEncoding - Skip URI encoding (default: false)
 * @returns String representation of URI
 */
toString(skipEncoding?: boolean): string;

import { URI } from "vscode-uri";

const uri = URI.file('/path with spaces/file#name.txt');

// Normal encoding (default)
console.log(uri.toString()); // Encoded URI string

// Skip encoding for display purposes
console.log(uri.toString(true)); // Human-readable URI string