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

    Class RootPathUrl

    A rooted URL instance, i.e. with a pathname that starts with '/', but without an origin.

    Analogous to AbsolutePath, but for URLs; i.e. it may have query paramaters and a fragment, and has methods to work with them.

    To convert to a full URL with an origin, see FullPathUrl#resolve

    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.

    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).

    Hierarchy (View Summary)

    Implements

    Index

    Constructors

    constructor

    Accessors

    extension filename fragment isDirectory parent pathname query segments stem

    Methods

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

    Constructors

    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 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 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 | RootPathUrl

        An absolute path or string to check against.

      • Optionalopts: { includeSelf?: boolean }

      Returns boolean

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

      Query and fragment are ignored.

      const p1 = new RootPathUrl('/project')
      const p2 = new RootPathUrl('/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.

    • 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

      const p1 = new RootPathUrl('/project')
      const p2 = new RootPathUrl('/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.

    • 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

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

    • 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