@thingts/path - v1.0.5
    Preparing search index...

    Class AbsolutePath

    Represents an absolute filesystem path (i.e. a path starting at the root, i.e. has a leading separator), and provides methods for path resolution, manipulation and queries.

    AbsolutePath instances are normalized and immutable.

    AbsolutePath has the same functionality as RelativePath but with additional methods that are only valid for absolute paths: resolve, relativeTo, and descendsFrom.

    Note that AbsolutePath provides pure path manipulation, it does not access the filesystem in any way. (If you want to work with the filesystem, you can use the @thingts/fs-path library which extends AbsolutePath with filestem operations.)

    const p1 = new AbsolutePath('/project/demos')
    const p2 = p1.join('demo1/src', 'index.ts') // '/project/demos/demo1/src/index.ts'
    console.log(p2.descendsFrom(p1)) // true
    console.log(p2.relativeTo(p1)) // 'demo1/src/index.ts' (RelativePath)

    Hierarchy

    • PathBase
      • AbsolutePath
    Index

    Constructors

    constructor

    Accessors

    extension filename parent stem

    Methods

    descendsFrom equals join newSelf relativeTo replaceExtension replaceFilename replaceParent replaceStem resolve toString transformFilename isAbsolutePathString

    Constructors

    • Create a new AbsolutePath from a string or another AbsolutePath.

      The path is normalized and guaranteed to be absolute. Any trailing separator is removed.

      Throws an error if the provided path is not absolute.

      Parameters

      Returns AbsolutePath

      new AbsolutePath('/project/demos') // OK
      new AbsolutePath('project/demos')  // Throws Error
      new AbsolutePath('/project//src/../demos/') // normalized => /project/demos

    Accessors

    • get extension(): string

      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

    • get filename(): Filename

      The filename component (last path segment) as a Filename.

      Returns Filename

      new AbsolutePath('/a/b/c.txt').filename // 'c.txt' (Filename)
      new RelativePath('a/b/c.txt').filename  // 'c.txt' (Filename)
    • get parent(): this

      The parent directory of this path.

      Returns this

      A new path instance pointing to the parent.

      new AbsolutePath('/a/b/c.txt').parent // '/a/b' (AbsolutePath)
      new RelativePath('a/b/c.txt').parent  // 'a/b' (RelativePath)
    • get stem(): string

      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

    Methods

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

      Parameters

      • ancestor: string | AbsolutePath

        An AbsolutePath or string to check against.

      • Optionalopts: { includeSelf?: boolean }
        • OptionalincludeSelf?: boolean

          If true, return true when the paths are identical.

      Returns boolean

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

      const p1 = new AbsolutePath('/project/demo')
      const p2 = new AbsolutePath('/project/demo/src/index.ts')
      console.log(p2.descendsFrom(p1)) // true
      console.log(p1.descendsFrom(p1)) // false
      console.log(p1.descendsFrom(p1, { includeSelf: true })) // true

    • Returns true if this path equals the other path or string

      Parameters

      • other: string | PathBase

      Returns boolean

    • Join additional path segments to this path.

      Accepts strings or path objects; null and undefined are ignored. The resulting path is normalized.

      Parameters

      • ...segments: readonly (undefined | null | string | FilenameBase)[]

      Returns this

      A new path instance with the segments appended

      const a1 = new AbsolutePath('/project/demo')
      const a2 = a1.join('demo1/src', 'index.js') // '/project/demo/demo1/src/index.js'
      a2 instanceof AbsolutePath // true

      const r1 = new RelativePath('demo')
      const r2 = r1.join('demo1/src', 'index.js') // 'demo/demo1/src/index.js'
      r2 instanceof RelativePath // true

    • Protected factory to construct a new instance of the current class, with the given path.

      Used by all mutation-like methods to return a new instance of the same class, allowing derived classes that inherit those methods to return new instances of themselves without needing to override them.

      The default implementation assumes the derived class's constructor takes a single string argument (the path). Derived classes with different constructor siguatures should override newSelf.

      Parameters

      • path: string | FilenameBase

      Returns this

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

      Parameters

      Returns RelativePath

      A RelativePath that goes from base to this.

      const p1 = new AbsolutePath('/project/demo')
      const p2 = new AbsolutePath('/project/demo/src/index.ts')
      const rel = p2.relativeTo(p1) // 'src/index.ts' (RelativePath)
      p1.join(rel).equals(p2)       // true

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

      Parameters

      • newExt: string

        New extension, e.g. json or .json

      Returns this

      A new path with the extension replaced.

      new AbsolutePath('/a/b/c.txt').replaceExtension('json') // '/a/b/c.json' (AbsolutePath)
      new RelativePath('a/b/c.txt').replaceExtension('.json') // '/a/b/c.json' (RelativePath)

    • Replace the filename (last segment).

      Parameters

      Returns this

      A new path with the filename replaced.

    • Replace the parent directory while keeping the current filename.

      Parameters

      • newParent: string | PathBase

        Parent directory as string or another PathBase.

      Returns this

      A new path rooted at newParent with the same filename.

      new AbsolutePath('/old/file.txt').replaceParent('/new/dir') // '/new/dir/file.txt' (AbsolutePath)
      new RelativePath('old/file.txt').replaceParent('new/dir')   // 'new/dir/file.txt' (RelativePath)

    • Replace the filename stem, keeping the extension the same

      Parameters

      • newStem: string

        New stem to use (extension is preserved).

      Returns this

      A new path with the stem replaced.

      new AbsolutePath('/a/b/c.txt').replaceStem('d') // '/a/b/d.txt' (AbsolutePath)
      new RelativePath('a/b/c.txt').replaceStem('d')  // 'a/b/d.txt' (RelativePath)

    • Resolve additional path segments against this absolute path.

      Accepts strings, Filename, RelativePath, or AbsolutePath objects. Null and undefined segments are ignored.

      Similar to join, except that if any segment is an AbsolutePath or string starting with a path separator, the current path is discarded and resolution starts from that segment.

      Parameters

      Returns this

      A new AbsolutePath with the resolved path.

      const p1 = new AbsolutePath('/project/demos')
      const p2 = p1.resolve('demo1/src', 'index.ts') // '/project/demos/demo1/src/index.ts'
      const p3 = p1.resolve('/etc/config') // '/etc/config' (resets to absolute path)

    • Returns the path as string.

      Returns string

    • Transform the filename via a callback.

      Parameters

      Returns this

      A new path with the transformed filename.

      p.transformFilename(f => String(f).toUpperCase())

    • Checks whether a string is an absolute path. (I.e., if it would be acceptable to the AbsolutePath constructor.)

      Parameters

      • filepath: string

        The string to check.

      Returns boolean

      True if the string is an absolute path, otherwise false.

    Settings

    Member Visibility

    On This Page

    Constructors
    Accessors
    Methods