@thingts/path - v2.0.4
    Preparing search index...

    Class FullPathUrl

    Fully qualified URL with origin, pathname, query, and fragment, for URLs that have paths, specifically the "special schemes": http://, https://, ftp://, ftps://, ws://, wss://, and file://.

    Analogous to AbsolutePath but for Full URLs, i.e. it has an origin (e.g. https://example.com:8080) and may have query parameters and a fragment, and has methods to work with them.

    Has the same capabilities as RootPathUrl, but requires an origin, and provides methods to work with the origin and for conversion to/from the standard URL class.

    On construction, URL path classes normalize the path:

    • As with plain paths, repeated slashes are merged, and . and .. components are resolved.
    • Unlike plain paths, trailing slashes are preserved to indicate directory paths (see .isDirectory).
    • Percent-encoded characters in the pathname (nor other parts) are not decoded, they are preserved as-is.
    • The origin is normalized to lowercase scheme and host.

    When converting to a string, the result is encoded as needed:

    • Illegal characters in the pathname, query, or fragment are percent-encoded.
    • Existing percent-encoded characters in the pathname, query, or fragment are preserved as-is (not double-encoded).
    const url1 = new FullPathUrl('https://example.com:8080/foo/bar/baz.txt?query=1#frag')
    const url2 = new FullPathUrl({
      origin: 'https://example.com:8080',
      pathname: '/foo/bar/baz.txt',
      query: { query: '1' },
      fragment: 'frag'
    })
    url1.equals(url2) // → true
    url1.toURL()      // → URL('https://example.com:8080/foo/bar/baz.txt?query=1#frag')
    url1.href         // → 'https://example.com:8080/foo/bar/baz.txt?query=1#frag'
    url1.rootPath     // → RootPathUrl('/foo/bar/baz.txt?query=1#frag')

    const url3 = new FullPathUrl({
        origin: 'HTTPS://Example.com:8080',
        pathname: '/foo bar/baz.txt',
        query: { 'a b': 'c d??' },
        fragment: 'my fragment #1'
    })

    url3.origin   // → 'https://example.com:8080'
    url3.pathname // → '/foo bar/baz.txt'
    url3.query    // → { 'a b': 'c d??' }
    url3.fragment // → 'my fragment #1'
    url3.href     // → 'https://example.com:8080/foo%20bar/baz.txt?a%20b=c%20d%3F%3F#my%20fragment%20%231'

    Hierarchy (View Summary)

    Implements

    Index

    Constructors

    constructor

    Accessors

    extension filename fragment href isDirectory origin parent pathname query rootPath segments stem

    Methods

    descendsFrom equals join mergeQuery relativeTo removeFragment removeQuery replaceExtension replaceFilename replaceFragment replaceOrigin replaceParent replacePathname replaceQuery replaceStem resolve toString toURL transformFilename unDirectory

    Constructors

    • Creates a new FullPathUrl instance from the given URL, string or parts.

      Parameters

      Returns FullPathUrl

      Throws an error if given a string that does not properly parse to a full URL, or if given a scheme that is not one of: http:, https:, ftp:, ftps:, ws:, 'wss:', or file:

      const url1 = new FullPathUrl('https://example.com:8080/foo/bar/baz.txt?query=1#frag')
      const url2 = new FullPathUrl({
        origin: 'https://example.com:8080',
        pathname: '/foo/bar/baz.txt',
        query: { query: '1' },
        fragment: 'frag'
      })

    Accessors

    • get extension(): string | undefined

      Returns the extension of the filename including the leading dot, as a string. If the filename has no extension, returns an empty string.

      Note that if the filename starts with a dot (e.g. .gitignore), that dot is considered part of the stem. So .gitignore has extension '' and .gitignore.bak has extension .bak

      Returns string | undefined

      If the pathname ends with a slash (i.e. this.isDirectory === true) there is no filename, and so this.extension returns undefined

    • get fragment(): string | undefined

      The fragment (hash) component of the URL, without the leading #.

      Note a distinction between an empty fragment and no fragment:

      • empty - '' - The URL has a hash, but with nothing after it
      • no fragment - undefined - The URL has no hash at all

      Returns string | undefined

    • get isDirectory(): boolean

      In URL strings a trailing slash is significant -- it nominally signifies a directory (e.g. http://example.com/foo/bar/) vs. a file or resource.

      And so if a URL path's instances .pathname ends with a slash, it is considered a directory, and its .filename is undefined. If it does not end with a slash, its final segment is considered the filename, same as for plain paths.

      A pathname consisting of a single dot (.) is also considered a directory.

      To remove the directory designation (i.e. remove the trailing slash) from a URL path, use unDirectory(); to create a directory designation (i.e. add a trailing slash, use join('/').

      Returns boolean

      Returns true if this URL's .pathname ends with a slash

    • get origin(): string

      Returns the origin (scheme + authority) portion of the URL.

      Returns string

      const url = new FullPathUrl('https://example.com:8080/foo/bar/baz.txt?query=1#frag')
      url.origin // → 'https://example.com:8080'
    • get parent(): this

      Returns this

      Returns a new URL instance for parent directory of this URL. The new instance always has .isDirectory true, and keeps the same query and hash as this.

    • get rootPath(): RootPathUrl

      Returns a RootPathUrl representing the root path of this URL, including the query and fragment (if any) -- I.e. this URL without the origin.

      Returns RootPathUrl

      const url = new FullPathUrl('https://example.com:8080/foo/bar/baz.txt?query=1#frag')
      url.rootPath // → RootPathUrl('/foo/bar/baz.txt?query=1#frag')
    • get segments(): string[]

      The segments of this path as an array of strings.

      Returns string[]

      If the pathname ends with a slash (i.e. this.isDirectory === true) there is no filename, the last segment in the array will be the last directory name.

    • get stem(): string | undefined

      Returns the stem of the filename, i.e. the part before the extension. If the filename has no extension, returns the entire filename

      Note that if the filename starts with a dot (e.g. .gitignore), that dot is considered part of the stem. So .gitignore and .gitignore.bak both have stem .gitignore

      Returns string | undefined

      If the pathname ends with a slash (i.e. this.isDirectory === true) there is no filename, and so this.stem returns undefined

    Methods

    • Test whether this path is a descendant of the given ancestor path.

      Parameters

      • ancestor: string | FullPathUrl

        An absolute path or string to check against.

      • Optionalopts: { includeSelf?: boolean }

      Returns boolean

      True if this path descends from the ancestor, otherwise false.

      The origin is also compared; if the origins differ, this method returns false.

      Query and fragment are ignored.

      const p1 = new FullPathUrl('http://example.com/project')
      const p2 = new FullPathUrl('http://example.com/project/src/index.ts')
      p2.descendsFrom(p1)                        // → true
      p1.descendsFrom(p1)                        // → false
      p1.descendsFrom(p1, { includeSelf: true }) // → true

    • Join additional path segments to this URL's pathname.

      Accepts relative path objects and Filename segment arguments for type safety, but you can also directly pass strings for convenience. All args are stringified and interpreted as segments to be joined, regardless of whether they start with a path separator or URL origin.

      In addition to joining path segments, .join() also merges queries and fragments from the given segments into the resulting URL: as the args are processed, any query encountered will be merged into the current query using the semantics of mergeQuery(), and any fragment will replace the current fragment.

      (It's not possible to remove an existing query parameter or the entire query or an existing framgent using .join(), only to add/replace them, although they can be replaced with '')

      Any null, undefined, or empty segments are ignored.

      Parameters

      Returns this

      A new instance with the segments appended and resulting pathname normalized, and queries and fragments merged.

       const url    = new FullPathUrl('/foo/bar?x=1#frag')
       const result = url.join('more', '/other/path?x=2&y=2#fragB', 'final.txt#fragC')
               // → FullPathUrl('/foo/bar/more/other/path/final.txt?x=2&y=2#fragC')

    • Merges the given query parameters into the URL's existing query parameters, returning a new instance with the merged result.

      The merge overwrite the values of the existing query for whichever keys are given in the provided query. If there is no current query, or if the current query is empty, this has the same effect as replaceQuery().

      Parameters

      Returns this

      url.replaceQuery({ a: '1', b: '2' })          // ?a=1&b=2
      url.mergeQuery({ b: '3', c: '4' })    // ?a=1&b=3&c=4

      url.replaceQuery({ arr: ['1', '2'] })          // ?arr=1&arr=2
      url.mergeQuery({ arr: [...url.query.arr, '3'] }) // ?arr=1&arr=2&arr=3

    • Compute the relative path from the given base path to this path.

      Parameters

      • base: this

        The base absolute path.

      Returns RelativePathUrl

      A relative path that goes from base to this.

      The returned RelativePathUrl has the same query and fragment as this

      Throws an error if the two origins differ

      const p1 = new FullPathUrl('http://example.com/project')
      const p2 = new FullPathUrl('http://example.com/project/src/index.ts?q=1#frag')
      const rel = p2.relativeTo(p1)

    • Replace the filename extension, keeping the stem the same. The passed string can include or omit the leading dot; if omitted, it will be added.

      Parameters

      • newExtension: string

        New extension, e.g. json or .json

      Returns this

      A new instance with the filename extension replaced.

    • Parameters

      • fragment: string

      Returns this

      Returns a new instance with the given fragment (hash) string, replacing the current fragment (if any).

      For convenience, a single leading # in fragment will be stripped; if you want a leading # to be part of the fragment, use ##

      You can provide an empty string to create an empty fragment; to remove the fragment entirely, use removeFragment.

    • Parameters

      Returns this

      A new FullPathUrl instance with the origin replaced with the given value.

      const url = new FullPathUrl('https://example.com/foo/bar')
      url.replaceOrigin('http://another.com') // → FullPathUrl('http://another.com/foo/bar')

    • Similar to join(), but as the args are processed, if a root-relative (i.e. absolute) pathname is encountered, the current pathname, query and fragment are discarded and are replaced by those of that argument.

      @see join

      Parameters

      Returns this

      As the args are processed, if a full URL (i.e. origin + pathname starting with '/') is encountered, the entire current URL is discarded (origin, pathname, query, fragment) and replaced with that argument.

      resolve() can be used to convert a RootPathUrl or RelativePathUrl to a FullPathUrl (see examples).

      const url = new FullPathUrl('http://example.com/project/src?x=1#frag')
      url.resolve('lib/utils', '../index.ts', '?y=2', '#newfrag') // → FullPathUrl('http://example.com/project/src/lib/index.ts?y=2#newfrag')
      url.resolve('lib', '/other/path/file.txt&z=3')              // → FullPathUrl('http://example.com/other/path/file.txt?z=3')
      url.resolve('http://another.com/new/path')                  // → FullPathUrl('http://another.com/new/path')

      // Converting a RootPathUrl to FullPathUrl
      const root = new RootPathUrl('/project/src/index.ts?x=1#frag')
      const rel = new RelativePathUrl('project/src/index.ts?x=1#frag')
      new FullPathUrl('http://example.com/').resolve(rootPath) // → FullPathUrl('http://example.com/project/src/index.ts?x=1#frag')
      new FullPathUrl('http://example.com/').resolve(relPath)  // → FullPathUrl('http://example.com/project/src/index.ts?x=1#frag')

      rootPath

    • Returns URL

      Returns a new URL instance representing this FullPathUrl.

      const url = new FullPathUrl('https://example.com:8080/foo/bar/baz.txt?query=1#frag')
      url.toURL() // → URL('https://example.com:8080/foo/bar/baz.txt?query=1#frag')

    • Returns this

      Returns a new instance with the directory designation removed, i.e. the final slash (if any) is removed from the pathname.

      Exception: For FullPathUrl and RootPathUrl, if the pathname is a single slash (/), it is not removed, and the new instance will be the same as the current instance (i.e. unDirectory is a no-op on a root directory)

    Settings

    Member Visibility

    On This Page

    Constructors
    Accessors
    Methods