• Public
  • Public/Protected
  • All

Class Uri

A universal resource identifier representing either a file on disk or another resource, like untitled resources.


  • Uri






Static parse

  • parse(value: string, strict?: boolean): Uri
  • Create an URI from a string, e.g. http://www.example.com/some/path, file:///usr/home, or scheme:with/path.

    Note that for a while uris without a scheme were accepted. That is not correct as all uris should have a scheme. To avoid breakage of existing code the optional strict-argument has been added. We strongly advise to use it, e.g. Uri.parse('my:uri', true)




    • value: string

      The string value of an Uri.

    • Optional strict: boolean

      Throw an error when value is empty or when no scheme can be parsed.

    Returns Uri

    A new Uri instance.

Static file

  • file(path: string): Uri
  • Create an URI from a file system path. The scheme will be file.

    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';


    • path: string

      A file system or UNC path.

    Returns Uri

    A new Uri instance.

Static joinPath

  • joinPath(base: Uri, ...pathSegments: string[]): Uri
  • Create a new uri which path is the result of joining the path of the base uri with the provided path segments.

    • Note 1: joinPath only affects the path component and all other components (scheme, authority, query, and fragment) are left as they are.
    • Note 2: The base uri must have a path; an error is thrown otherwise.

    The path segments are normalized in the following ways:

    • sequences of path separators (/ or \) are replaced with a single separator
    • for file-uris on windows, the backslash-character (\) is considered a path-separator
    • the ..-segment denotes the parent segment, the . denotes the current segment
    • paths have a root which always remains, for instance on windows drive-letters are roots so that is true: joinPath(Uri.file('file:///c:/root'), '../../other').fsPath === 'c:/other'


    • base: Uri

      An uri. Must have a path.

    • Rest ...pathSegments: string[]

      One more more path fragments

    Returns Uri

    A new uri which path is joined with the given fragments

Static from

  • from(components: { scheme: string; authority?: string; path?: string; query?: string; fragment?: string }): Uri
  • Create an URI from its component parts




    • components: { scheme: string; authority?: string; path?: string; query?: string; fragment?: string }

      The component parts of an Uri.

      • Readonly scheme: string
      • Optional Readonly authority?: string
      • Optional Readonly path?: string
      • Optional Readonly query?: string
      • Optional Readonly fragment?: string

    Returns Uri

    A new Uri instance.


  • with(change: { scheme?: string; authority?: string; path?: string; query?: string; fragment?: string }): Uri
  • Derive a new Uri from this Uri.

    let file = Uri.parse('before:some/file/path');
    let other = file.with({ scheme: 'after' });
    assert.ok(other.toString() === 'after:some/file/path');


    • change: { scheme?: string; authority?: string; path?: string; query?: string; fragment?: string }

      An object that describes a change to this Uri. To unset components use null or the empty string.

      • Optional scheme?: string
      • Optional authority?: string
      • Optional path?: string
      • Optional query?: string
      • Optional fragment?: string

    Returns Uri

    A new Uri that reflects the given change. Will return this Uri if the change is not changing anything.


  • toString(skipEncoding?: boolean): string
  • Returns a string representation of this Uri. The representation and normalization of a URI depends on the scheme.

    • The resulting string can be safely used with Uri.parse.
    • The resulting string shall not be used for display purposes.

    Note that the implementation will encode aggressive which often leads to unexpected, but not incorrect, results. For instance, colons are encoded to %3A which might be unexpected in file-uri. Also & and = will be encoded which might be unexpected for http-uris. For stability reasons this cannot be changed anymore. If you suffer from too aggressive encoding you should use the skipEncoding-argument: uri.toString(true).


    • Optional skipEncoding: boolean

      Do not percentage-encode the result, defaults to false. Note that the # and ? characters occurring in the path will always be encoded.

    Returns string

    A string representation of this Uri.


  • toJSON(): any
  • Returns a JSON representation of this Uri.

    Returns any

    An object.


Private constructor

  • new Uri(scheme: string, authority: string, path: string, query: string, fragment: string): Uri
  • Use the file and parse factory functions to create new Uri objects.


    • scheme: string
    • authority: string
    • path: string
    • query: string
    • fragment: string

    Returns Uri


Readonly scheme

scheme: string

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

Readonly authority

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 path

path: string

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

Readonly query

query: string

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

Readonly fragment

fragment: string

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

Readonly fsPath

fsPath: string

The string representing the corresponding file system path of this Uri.

Will handle UNC paths and normalize windows drive letters to lower-case. Also 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 resulting string shall not be used for display purposes but for disk operations, like readFile et al.

The difference to the path-property is the use of the platform specific path separator and the handling of UNC paths. The sample below outlines the difference:

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'

Generated by TypeDoc. Maintained by 洛竹