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/')