docs: "what is this?", "when should i use this?", api, types

Signed-off-by: Lexus Drumgold <[email protected]>

src/interfaces/pathe.ts

@@ -47,7 +47,7 @@ interface Pathe extends PlatformPath {
    *
    * @param {string} path - Path to evaluate
    * @param {Nullable<string>} [ext] - Default file extension
-   * @param {string[]} [ignore] - File extensions to ignore if present
+   * @param {string[]} [ignore] - File extensions to ignore if found
    * @return {string} `path` unmodified or with `ext` appended
    * @throws {TypeError} If `path` is not a string or `ext` is not a string
    */

src/interfaces/platform-path.ts

@@ -28,7 +28,7 @@ interface PlatformPath {
   /**
    * Path segment separator.
    *
-   * **Note**: Also known as "directory separator".
+   * Also known as a "directory separator".
    *
    * @readonly
    */
@@ -71,10 +71,10 @@ interface PlatformPath {
   dirname(path: string): string
 
   /**
-   * Returns the extension of the given `path`, from the last occurrence of the
-   * `.` (dot) character to end of the string in the last portion of the path.
+   * Returns the extension of a `path`, from the last occurrence of the `.`
+   * (dot) character to end of the string in the last portion of the path.
    *
-   * If there is no `.` in the last portion of the path, or if there are no `.`
+   * If there is no `.` in the last portion of `path`, or if there are no  `.`
    * characters other than the first character of the path's [`basename`][1], an
    * empty string will be returned.
    *
@@ -87,7 +87,8 @@ interface PlatformPath {
   extname(path: string): EmptyString | Ext
 
   /**
-   * Returns a path string from an object - the opposite of [`parse()`][1].
+   * Returns a path string from an object — the opposite of
+   * [`parse()`][1].
    *
    * When adding properties to `pathObject`, there are combinations where one
    * property has priority over another:
@@ -130,7 +131,7 @@ interface PlatformPath {
    *
    * [1]: {@link ../lib/sep.ts}
    *
-   * @param {string[]} paths - A sequence of path segments
+   * @param {string[]} paths - Path segment sequence
    * @return {string} Path segment sequence, `paths`, as one path
    * @throws {TypeError} If any segment in `paths` is not a string
    */
@@ -213,7 +214,7 @@ interface PlatformPath {
    *
    * [1]: {@link ../lib/sep.ts}
    *
-   * @param {string[]} paths - A sequence of path segments
+   * @param {string[]} paths - Path segment sequence
    * @return {string} Path segment sequence, `paths`, as absolute path
    * @throws {TypeError} If any segment in `paths` is not a string
    */
@@ -226,7 +227,7 @@ interface PlatformPath {
    * returned without modifications.
    *
    * [1]: https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file#namespaces
-   * [2]: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions
+   * [2]: https://learn.microsoft.com/windows/win32/fileio/naming-a-file#naming-conventions
    * [3]: https://learn.microsoft.com/dotnet/standard/io/file-path-formats#unc-paths
    *
    * @param {string} path - Path to evaluate

src/lib/extname.ts

@@ -12,10 +12,10 @@ import type { Ext } from '#src/types'
 import type { EmptyString } from '@flex-development/tutils'
 
 /**
- * Returns the extension of the given `path`, from the last occurrence of the
- * `.` (dot) character to end of the string in the last portion of the path.
+ * Returns the extension of a `path`, from the last occurrence of the `.` (dot)
+ * character to end of the string in the last portion of the path.
  *
- * If there is no `.` in the last portion of the path, or if there are no `.`
+ * If there is no `.` in the last portion of `path`, or if there are no  `.`
  * characters other than the first character of the path's [`basename`][1], an
  * empty string will be returned.
  *

src/lib/format.ts

@@ -10,7 +10,7 @@ import formatExt from '#src/utils/format-ext'
 import sep from './sep'
 
 /**
- * Returns a path string from an object - the opposite of [`parse()`][1].
+ * Returns a path string from an object — the opposite of [`parse`][1].
  *
  * When adding properties to `pathObject`, there are combinations where one
  * property has priority over another:

src/lib/join.ts

@@ -20,7 +20,7 @@ import sep from './sep'
  *
  * [1]: {@link ./sep.ts}
  *
- * @param {string[]} paths - A sequence of path segments
+ * @param {string[]} paths - Path segment sequence
  * @return {string} Path segment sequence, `paths`, as one path
  * @throws {TypeError} If any segment in `paths` is not a string
  */

src/lib/parse.ts

@@ -18,14 +18,14 @@ import sep from './sep'
 
 /**
  * Returns an object whose properties represent significant elements of the
- * given `path`. Trailing directory [separators][1] are ignored.
+ * given `path`. Trailing [directory separators][1] are ignored.
  *
- * **Note**: Unlike in Node.js, `pathe.parse(path).dir === pathe.dirname(path)`
- * when `path` is a non-empty string. See [`nodejs/node#18655`][3] for details.
+ * **Note**: `parse(path).dir === dirname(path)` when `path` is a non-empty
+ * string. This is stark contrast to `node:path`. See [`nodejs/node#18655`][2]
+ * for details.
  *
  * [1]: {@link ./sep.ts}
- * [2]: {@link ./dirname.ts}
- * [3]: https://github.com/nodejs/node/issues/18655
+ * [2]: https://github.com/nodejs/node/issues/18655
  *
  * @param {string} path - Path to evaluate
  * @return {ParsedPath} Object representing significant elements of `path`

src/lib/resolve.ts

@@ -34,7 +34,7 @@ import sep from './sep'
  *
  * [1]: {@link ./sep.ts}
  *
- * @param {string[]} paths - A sequence of path segments
+ * @param {string[]} paths - Path segment sequence
  * @return {string} Path segment sequence, `paths`, as absolute path
  * @throws {TypeError} If any segment in `paths` is not a string
  */

src/lib/sep.ts

@@ -8,7 +8,7 @@ import type { Sep } from '#src/types'
 /**
  * Path segment separator.
  *
- * **Note**: Also known as "directory separator".
+ * Also known as a "directory separator".
  *
  * @const {Sep} sep
  */

src/lib/to-namespaced-path.ts

@@ -17,8 +17,8 @@ import sep from './sep'
  * If `path` is not a [drive path][2] or [UNC path][3], `path` will be returned
  * without modifications.
  *
- * [1]: https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file#namespaces
- * [2]: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions
+ * [1]: https://docs.microsoft.com/windows/desktop/FileIO/naming-a-file#namespaces
+ * [2]: https://learn.microsoft.com/windows/win32/fileio/naming-a-file#naming-conventions
  * [3]: https://learn.microsoft.com/dotnet/standard/io/file-path-formats#unc-paths
  *
  * @param {string} path - Path to evaluate

src/utils/__tests__/default-ext.spec.ts

@@ -9,8 +9,9 @@ describe('unit:utils/defaultExt', () => {
   it('should return path with ext appended', () => {
     // Arrange
     const cases: [...Parameters<typeof testSubject>, string][] = [
-      ['file', 'mjs', undefined, 'file.mjs'],
-      ['file.', '.mjs', undefined, 'file.mjs'],
+      ['file', 'mjs', [], 'file.mjs'],
+      ['file.', '.mjs', [], 'file.mjs'],
+      ['file.d', 'mts', ['.d'], 'file.d.mts'],
       ['file.min', 'mjs', ['.min'], 'file.min.mjs'],
       ['file.min', '.mjs', [null, '.min'] as string[], 'file.min.mjs']
     ]

src/utils/__tests__/format-ext.spec.ts

@@ -13,11 +13,21 @@ describe('unit:utils/formatExt', () => {
     ext = '.mjs'
   })
 
-  it('should return empty string if ext is empty string', () => {
-    expect(testSubject('')).to.equal('')
+  it('should return empty string if ext is empty', () => {
+    // Arrange
+    const cases: [...Parameters<typeof testSubject>, string][] = [
+      ['', ''],
+      [' ', ''],
+      [undefined, '']
+    ]
+
+    // Act + Expect
+    cases.forEach(([ext, expected]) => {
+      expect(testSubject(ext)).to.equal(expected)
+    })
   })
 
-  it('should return ext without modifications if ext starts with dot', () => {
+  it('should return ext if ext starts with dot character', () => {
     expect(testSubject(ext)).to.equal(ext)
   })
 

src/utils/add-ext.ts

@@ -18,9 +18,9 @@ import formatExt from './format-ext'
  * @example
  *  addExt('file', 'mjs') // 'file.mjs'
  * @example
- *  addExt('file.min', '.mjs') // 'file.min.mjs'
+ *  addExt('file', '.mjs') // 'file.mjs'
  * @example
- *  addExt('file.min.mjs', '.mjs') // 'file.min.mjs'
+ *  addExt('file.d.mts', '.mts') // 'file.d.mts'
  *
  * @param {string} path - Path to evaluate
  * @param {Nullable<string>} [ext] - File extension to add

src/utils/default-ext.ts

@@ -26,11 +26,11 @@ import formatExt from './format-ext'
  * @example
  *  defaultExt('file.mjs', '.mjs') // 'file.mjs'
  * @example
- *  defaultExt('file.min', '.mjs', ['.min']) // 'file.min.mjs'
+ *  defaultExt('file.d', '.mts', ['.d']) // 'file.d.mts'
  *
  * @param {string} path - Path to evaluate
  * @param {Nullable<string>} [ext] - Default file extension
- * @param {string[]} [ignore] - File extensions to ignore if present
+ * @param {string[]} [ignore] - File extensions to ignore if found
  * @return {string} `path` unmodified or with `ext` appended
  * @throws {TypeError} If `path` is not a string or `ext` is not a string
  */

src/utils/format-ext.ts

@@ -15,6 +15,17 @@ import type { EmptyString } from '@flex-development/tutils'
  *
  * Does nothing if a file extension isn't provided.
  *
+ * @example
+ *  formatExt() // ''
+ * @example
+ *  formatExt('') // ''
+ * @example
+ *  formatExt('.ts') // '.ts'
+ * @example
+ *  formatExt('mjs') // '.mjs'
+ * @example
+ *  formatExt('d.mts') // '.d.mts'
+ *
  * @param {string} [ext=''] - File extension to format
  * @return {EmptyString | Ext} Formatted file extension or empty string
  */

src/utils/remove-ext.ts

@@ -18,9 +18,9 @@ import formatExt from './format-ext'
  * @example
  *  removeExt('file.mjs', 'mjs') // 'file'
  * @example
- *  removeExt('file.mjs', '.ts') // 'file.mjs'
+ *  removeExt('file.mjs', '.mjs') // 'file'
  * @example
- *  removeExt('file.min.mjs', '.mjs') // 'file.min'
+ *  removeExt('file.d.mts', '.mjs') // 'file.d.mts'
  *
  * @param {string} path - Path to evaluate
  * @param {Nullable<string>} [ext] - File extension to removed