Class Uri

Expand description

Uniform Resource Identifier (Uri) http://tools.ietf.org/html/rfc3986. This class is a simple parser which creates the basic component parts (http://tools.ietf.org/html/rfc3986#section-3) with minimal validation and encoding.

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

Constructors§

§

new Uri(): Uri

Properties§

§readonly authority: string

authority is the 'www.example.com' part of 'http://www.example.com/some/path?query#fragment'. The part between the first double slashes and the next slash.

§readonly fragment: string

fragment is the 'fragment' part of 'http://www.example.com/some/path?query#fragment'.

§readonly path: string

path is the '/some/path' part of 'http://www.example.com/some/path?query#fragment'.

§readonly query: string

query is the 'query' part of 'http://www.example.com/some/path?query#fragment'.

§readonly scheme: string

scheme is the 'http' part of 'http://www.example.com/some/path?query#fragment'. The part before the first colon.

Accessors§

§

get fsPath(): string

Returns a string representing the corresponding file system path of this Uri. Will handle UNC paths, normalizes windows drive letters to lower-case, and uses the platform specific path separator.

  • Will not validate the path for invalid characters and semantics.
  • Will not look at the scheme of this Uri.
  • The result shall not be used for display purposes but for accessing a file on disk.

The difference to Uri#path is the use of the platform specific separator and the handling of UNC paths. See the below sample of a file-uri with an authority (UNC path).

const u = Uri.parse('file://server/c$/folder/file.txt')
u.authority === 'server'
u.path === '/shares/c$/file.txt'
u.fsPath === '\\server\c$\folder\file.txt'

Using Uri#path to read a file (using fs-apis) would not be enough because parts of the path, namely the server name, would be missing. Therefore Uri#fsPath exists - it's sugar to ease working with URIs that represent files on disk (file scheme).

Methods§

§

toJSON(): UriComponents

§

toString(skipEncoding?: boolean): string

Creates a string representation for this Uri. It's guaranteed that calling Uri.parse with the result of this function creates an Uri which is equal to this Uri.

  • The result shall not be used for display purposes but for externalization or transport.
  • The result will be encoded using the percentage encoding and encoding happens mostly ignore the scheme-specific encoding rules.
§

with(
    change: {
        authority?: string;
        fragment?: string;
        path?: string;
        query?: string;
        scheme?: string;
    },
): Uri

§

file(path: string): Uri

Creates a new Uri from a file system path, e.g. c:\my\files, /usr/home, or \\server\share\some\path.

The difference between Uri#parse and Uri#file is that the latter treats the argument as path, not as stringified-uri. E.g. Uri.file(path) is not the same as Uri.parse('file://' + path) because the path might contain characters that are interpreted (# and ?). See the following sample:

const good = Uri.file('/coding/c#/project1');
good.scheme === 'file';
good.path === '/coding/c#/project1';
good.fragment === '';
const bad = Uri.parse('file://' + '/coding/c#/project1');
bad.scheme === 'file';
bad.path === '/coding/c'; // path is now broken
bad.fragment === '/project1';
§

from(components: UriComponents, strict?: boolean): Uri

Creates new Uri from uri components.

Unless strict is true the scheme is defaults to be file. This function performs validation and should be used for untrusted uri components retrieved from storage, user input, command arguments etc

§

isUri(thing: unknown): thing is Uri

§

joinPath(uri: Uri, ...pathFragment: string[]): Uri

Join a Uri path with path fragments and normalizes the resulting path.

§

parse(value: string, _strict?: boolean): Uri

Creates a new Uri from a string, e.g. http://www.example.com/some/path, file:///usr/home, or scheme:with/path.

§

revive(data: Uri | UriComponents): Uri

A helper function to revive URIs.

Note that this function should only be used when receiving Uri#toJSON generated data and that it doesn't do any validation. Use Uri.from when received "untrusted" uri components such as command arguments or data from storage.

§

revive(data: Uri | UriComponents): Uri

A helper function to revive URIs.

Note that this function should only be used when receiving Uri#toJSON generated data and that it doesn't do any validation. Use Uri.from when received "untrusted" uri components such as command arguments or data from storage.

§

revive(data: Uri | UriComponents): Uri

A helper function to revive URIs.

Note that this function should only be used when receiving Uri#toJSON generated data and that it doesn't do any validation. Use Uri.from when received "untrusted" uri components such as command arguments or data from storage.

§

revive(data: Uri | UriComponents): Uri

A helper function to revive URIs.

Note that this function should only be used when receiving Uri#toJSON generated data and that it doesn't do any validation. Use Uri.from when received "untrusted" uri components such as command arguments or data from storage.