0
# VSCode URI
1

2
VSCode URI is a comprehensive URI implementation library specifically designed for Visual Studio Code and its extensions ecosystem. It offers robust parsing capabilities to decompose URI strings into their constituent components (scheme, authority, path, query, and fragment) following RFC 3986 standards, along with specialized utilities for path manipulation including joinPath, resolvePath, dirname, basename, and extname functions that use POSIX path semantics.
3

4
## Package Information
5

6
- **Package Name**: vscode-uri
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vscode-uri`
10

11
## Core Imports
12

13
```typescript
14
import { URI, Utils } from "vscode-uri";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { URI, Utils } = require("vscode-uri");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { URI, Utils } from "vscode-uri";
27

28
// Parse a URI from string
29
const uri = URI.parse('https://code.visualstudio.com/docs/extensions/overview#frag');
30
console.log(uri.scheme);    // 'https'
31
console.log(uri.authority); // 'code.visualstudio.com'
32
console.log(uri.path);      // '/docs/extensions/overview'
33
console.log(uri.fragment);  // 'frag'
34

35
// Create URI from filesystem path
36
const fileUri = URI.file('/users/me/project/file.txt');
37
console.log(fileUri.toString()); // 'file:///users/me/project/file.txt'
38

39
// Path manipulation utilities
40
const joined = Utils.joinPath(fileUri, 'subfolder', 'another.txt');
41
const parent = Utils.dirname(fileUri);
42
const filename = Utils.basename(fileUri);
43
```
44

45
## Architecture
46

47
VSCode URI is built around two main components:
48

49
- **URI Class**: Core RFC 3986 compliant URI implementation with parsing, serialization, and manipulation methods
50
- **Utils Namespace**: POSIX-compatible path manipulation utilities that work with URI instances
51
- **Cross-Platform Support**: Handles Windows and Unix path conventions with proper encoding/decoding
52
- **Performance Optimization**: Custom encoding routines and caching for optimal performance
53

54
## Capabilities
55

56
### URI Manipulation
57

58
Complete URI parsing, creation, and manipulation functionality following RFC 3986 standards. Supports parsing from strings, creating from filesystem paths, and building from components.
59

60
```typescript { .api }
61
class URI {
62
  readonly scheme: string;
63
  readonly authority: string;
64
  readonly path: string;
65
  readonly query: string;
66
  readonly fragment: string;
67
  readonly fsPath: string;
68

69
  static parse(value: string, strict?: boolean): URI;
70
  static file(path: string): URI;
71
  static from(components: UriComponents): URI;
72
  static isUri(thing: any): thing is URI;
73
  static revive(data: UriComponents | URI | undefined | null): URI | undefined | null;
74

75
  with(change: {
76
    scheme?: string;
77
    authority?: string | null;
78
    path?: string | null;
79
    query?: string | null;
80
    fragment?: string | null;
81
  }): URI;
82
  toString(skipEncoding?: boolean): string;
83
  toJSON(): UriComponents;
84
}
85

86
interface UriComponents {
87
  scheme: string;
88
  authority: string;
89
  path: string;
90
  query: string;
91
  fragment: string;
92
}
93
```
94

95
[URI Operations](./uri-operations.md)
96

97
### Path Utilities
98

99
POSIX-compatible path manipulation utilities for working with URI paths. All operations use forward slashes and follow POSIX path semantics regardless of platform.
100

101
```typescript { .api }
102
namespace Utils {
103
  function joinPath(uri: URI, ...paths: string[]): URI;
104
  function resolvePath(uri: URI, ...paths: string[]): URI;
105
  function dirname(uri: URI): URI;
106
  function basename(uri: URI): string;
107
  function extname(uri: URI): string;
108
}
109
```
110

111
[Path Utilities](./path-utilities.md)