vscode-uri

What is vscode-uri?

The vscode-uri npm package provides utilities to handle URIs within VS Code extensions. It allows developers to parse, manipulate, and work with URIs in a way that is consistent with the internal URI handling of Visual Studio Code.

What are vscode-uri's main functionalities?

Parsing URIs

This feature allows developers to parse a string URI into a URI object, enabling easy access to different parts of the URI such as scheme, path, query, and fragment.

const { URI } = require('vscode-uri');
const uri = URI.parse('https://example.com/path?query#fragment');
console.log(uri.scheme); // 'https'

Creating URIs

This feature enables the creation of URI objects from individual components, allowing for dynamic construction of URIs from various parts.

const { URI } = require('vscode-uri');
const uri = URI.from({ scheme: 'https', authority: 'example.com', path: '/path', query: 'query', fragment: 'fragment' });
console.log(uri.toString()); // 'https://example.com/path?query#fragment'

Modifying URIs

This functionality allows for the modification of existing URI objects, which is useful for changing parts of the URI without needing to reconstruct it entirely.

const { URI } = require('vscode-uri');
let uri = URI.parse('https://example.com/path');
uri = uri.with({ path: '/newPath' });
console.log(uri.toString()); // 'https://example.com/newPath'

Other packages similar to vscode-uri

urijs

urijs is a versatile URI manipulation library that offers similar functionalities to vscode-uri, such as parsing, manipulation, and serialization of URIs. Compared to vscode-uri, urijs provides a more extensive set of URI manipulation capabilities and does not tie specifically to any editor environment.

url-parse

url-parse is another library for parsing and manipulating URLs in a way similar to vscode-uri. It offers detailed parsing of URLs into components and works both in node and browser environments, making it more versatile compared to vscode-uri which is more focused on integration with VS Code.

README

vscode-uri

This module contains the URI implementation that is used by VS Code and its extensions. It has support for parsing a string into scheme, authority, path, query, and fragment URI components as defined in: http://tools.ietf.org/html/rfc3986

  foo://example.com:8042/over/there?name=ferret#nose
  \_/   \______________/\_________/ \_________/ \__/
   |           |            |            |        |
scheme     authority       path        query   fragment
   |   _____________________|__
  / \ /                        \
  urn:example:animal:ferret:nose

Usage

import { URI } from 'vscode-uri'

// parse an URI from string

let uri = URI.parse('https://code.visualstudio.com/docs/extensions/overview#frag')

assert.ok(uri.scheme === 'https');
assert.ok(uri.authority === 'code.visualstudio.com');
assert.ok(uri.path === '/docs/extensions/overview');
assert.ok(uri.query === '');
assert.ok(uri.fragment === 'frag');
assert.ok(uri.toString() === 'https://code.visualstudio.com/docs/extensions/overview#frag')


// create an URI from a fs path

let uri = URI.file('/users/me/c#-projects/');

assert.ok(uri.scheme === 'file');
assert.ok(uri.authority === '');
assert.ok(uri.path === '/users/me/c#-projects/');
assert.ok(uri.query === '');
assert.ok(uri.fragment === '');
assert.ok(uri.toString() === 'file:///users/me/c%23-projects/')

Usage: Util

This module also exports a Utils package which is an extension, not part of vscode.Uri, and useful for path-math. There is:

• Utils.joinPath(URI, paths): URI
• Utils.resolvePath(URI, paths): URI
• Utils.dirname(URI): string
• Utils.basename(URI): string
• Utils.extname(URI): string

All util use posix path-math as defined by the node.js path module.

Contributing

The source of this module is taken straight from the vscode-sources and because of that issues and pull request should be created in that repository. Thanks and Happy Coding!

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.