@file-services/types - npm Package Compare versions

Comparing version 2.1.0 to 2.2.0

cjs/path.d.ts

@@ -7,33 +7,19 @@ /**
     /**
-     * Platform-specific file separator. usually '\\' or '/'
+     * The platform-specific file separator. '\\' or '/'.
      */
-    sep: string;
+    readonly sep: string;
     /**
-     * Platform-specific file delimiter. usually ';' or ':'.
+     * The platform-specific file delimiter. ';' or ':'.
      */
-    delimiter: string;
+    readonly delimiter: string;
     /**
-     * Return the last portion of a path. Similar to the Unix basename command.
-     * Often used to extract the file name from a fully qualified path.
+     * Normalize a string path, reducing '..' and '.' parts.
+     * When multiple slashes are found, they're replaced by a single one; when the path contains a trailing slash, it is preserved. On Windows backslashes are used.
      *
-     * @param path the path to evaluate.
-     * @param ext optionally, an extension to remove from the result.
+     * @param p string path to normalize.
      */
-    basename(path: string, ext?: string): string;
+    normalize(p: string): string;
     /**
-     * Return the directory name of a path. Similar to the Unix dirname command.
-     *
-     * @param path the path to evaluate.
-     */
-    dirname(path: string): string;
-    /**
-     * Return the extension of the path, from the last '.' to end of string in the last portion of the path.
-     * If there is no '.' in the last portion of the path or the first character of it is '.',
-     * then it returns an empty string.
-     *
-     * @param path the path to evaluate.
-     */
-    extname(path: string): string;
-    /**
      * Join all arguments together and normalize the resulting path.
+     * Arguments must be strings. In v0.8, non-string arguments were silently ignored. In v0.10 and up, an exception is thrown.
      *
@@ -44,36 +30,114 @@ * @param paths paths to join.
     /**
-     * Normalize a string path, reducing '..' and '.' parts.
-     * When multiple slashes are found, they're replaced by a single one;
-     * when the path contains a trailing slash, it is preserved. On Windows backslashes are used.
+     * The right-most parameter is considered {to}.  Other parameters are considered an array of {from}.
      *
-     * @param path string path to normalize.
-     */
-    normalize(path: string): string;
-    /**
-     * The right-most parameter is considered {to}. Other parameters are considered an array of {from}.
-     * Starting from leftmost {from} paramter, resolves {to} to an absolute path.
+     * Starting from leftmost {from} parameter, resolves {to} to an absolute path.
      *
      * If {to} isn't already absolute, {from} arguments are prepended in right to left order,
-     * until an absolute path is found.
-     * If after using all {from} paths still no absolute path is found, the current working directory is used as well.
-     * The resulting path is normalized, and trailing slashes are removed unless the path gets resolved to the
-     * root directory.
+     * until an absolute path is found. If after using all {from} paths still no absolute path is found,
+     * the current working directory is used as well. The resulting path is normalized,
+     * and trailing slashes are removed unless the path gets resolved to the root directory.
      *
-     * @param pathSegments string paths to join.
+     * @param pathSegments string paths to join.  Non-string arguments are ignored.
      */
     resolve(...pathSegments: string[]): string;
     /**
+     * Determines whether {path} is an absolute path. An absolute path will always resolve to the same location, regardless of the working directory.
+     *
+     * @param path path to test.
+     */
+    isAbsolute(p: string): boolean;
+    /**
      * Solve the relative path from {from} to {to}.
-     * At times we have two absolute paths, and we need to derive the relative path from one to the other.
-     * This is actually the reverse transform of resolve().
+     * At times we have two absolute paths, and we need to derive the relative path from one to the other. This is actually the reverse transform of path.resolve.
      */
     relative(from: string, to: string): string;
     /**
-     * Determines whether {path} is an absolute path.
-     * An absolute path will always resolve to the same location, regardless of the working directory.
+     * Return the directory name of a path. Similar to the Unix dirname command.
      *
-     * @param path path to test.
+     * @param p the path to evaluate.
      */
-    isAbsolute(path: string): boolean;
+    dirname(p: string): string;
+    /**
+     * Return the last portion of a path. Similar to the Unix basename command.
+     * Often used to extract the file name from a fully qualified path.
+     *
+     * @param p the path to evaluate.
+     * @param ext optionally, an extension to remove from the result.
+     */
+    basename(p: string, ext?: string): string;
+    /**
+     * Return the extension of the path, from the last '.' to end of string in the last portion of the path.
+     * If there is no '.' in the last portion of the path or the first character of it is '.', then it returns an empty string
+     *
+     * @param p the path to evaluate.
+     */
+    extname(p: string): string;
+    /**
+     * Returns an object from a path string - the opposite of format().
+     *
+     * @param pathString path to evaluate.
+     */
+    parse(p: string): IParsedPath;
+    /**
+     * Returns a path string from an object - the opposite of parse().
+     */
+    format(pP: IFormatInputPathObject): string;
+    /**
+     * Posix specific pathing.
+     * Same as parent object on posix.
+     */
+    readonly posix: IFileSystemPath;
+    /**
+     * Windows specific pathing.
+     * Same as parent object on windows
+     */
+    readonly win32: IFileSystemPath;
 }
+/**
+ * A parsed path object generated by path.parse() or consumed by path.format().
+ */
+export interface IParsedPath {
+    /**
+     * The root of the path such as '/' or 'c:\'
+     */
+    root: string;
+    /**
+     * The full directory path such as '/home/user/dir' or 'c:\path\dir'
+     */
+    dir: string;
+    /**
+     * The file name including extension (if any) such as 'index.html'
+     */
+    base: string;
+    /**
+     * The file extension (if any) such as '.html'
+     */
+    ext: string;
+    /**
+     * The file name without extension (if any) such as 'index'
+     */
+    name: string;
+}
+export interface IFormatInputPathObject {
+    /**
+     * The root of the path such as '/' or 'c:\'
+     */
+    root?: string;
+    /**
+     * The full directory path such as '/home/user/dir' or 'c:\path\dir'
+     */
+    dir?: string;
+    /**
+     * The file name including extension (if any) such as 'index.html'
+     */
+    base?: string;
+    /**
+     * The file extension (if any) such as '.html'
+     */
+    ext?: string;
+    /**
+     * The file name without extension (if any) such as 'index'
+     */
+    name?: string;
+}
 //# sourceMappingURL=path.d.ts.map

package.json

 {
   "name": "@file-services/types",
   "description": "Common file system interfaces",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "main": "cjs/index.js",
@@ -22,4 +22,3 @@ "types": "cjs/index.d.ts",
   },
-  "sideEffects": false,
-  "gitHead": "d0f4daec4165377749c39bb159c24b6e0808fae4"
+  "sideEffects": false
 }

src/path.ts

@@ -7,81 +7,158 @@ /**
     /**
-     * Platform-specific file separator. usually '\\' or '/'
+     * The platform-specific file separator. '\\' or '/'.
      */
-    sep: string;
+    readonly sep: string;
 
     /**
-     * Platform-specific file delimiter. usually ';' or ':'.
+     * The platform-specific file delimiter. ';' or ':'.
      */
-    delimiter: string;
+    readonly delimiter: string;
 
     /**
-     * Return the last portion of a path. Similar to the Unix basename command.
-     * Often used to extract the file name from a fully qualified path.
+     * Normalize a string path, reducing '..' and '.' parts.
+     * When multiple slashes are found, they're replaced by a single one; when the path contains a trailing slash, it is preserved. On Windows backslashes are used.
      *
-     * @param path the path to evaluate.
-     * @param ext optionally, an extension to remove from the result.
+     * @param p string path to normalize.
      */
-    basename(path: string, ext?: string): string;
+    normalize(p: string): string;
 
     /**
-     * Return the directory name of a path. Similar to the Unix dirname command.
+     * Join all arguments together and normalize the resulting path.
+     * Arguments must be strings. In v0.8, non-string arguments were silently ignored. In v0.10 and up, an exception is thrown.
      *
-     * @param path the path to evaluate.
+     * @param paths paths to join.
      */
-    dirname(path: string): string;
+    join(...paths: string[]): string;
 
     /**
-     * Return the extension of the path, from the last '.' to end of string in the last portion of the path.
-     * If there is no '.' in the last portion of the path or the first character of it is '.',
-     * then it returns an empty string.
+     * The right-most parameter is considered {to}.  Other parameters are considered an array of {from}.
      *
-     * @param path the path to evaluate.
+     * Starting from leftmost {from} parameter, resolves {to} to an absolute path.
+     *
+     * If {to} isn't already absolute, {from} arguments are prepended in right to left order,
+     * until an absolute path is found. If after using all {from} paths still no absolute path is found,
+     * the current working directory is used as well. The resulting path is normalized,
+     * and trailing slashes are removed unless the path gets resolved to the root directory.
+     *
+     * @param pathSegments string paths to join.  Non-string arguments are ignored.
      */
-    extname(path: string): string;
+    resolve(...pathSegments: string[]): string;
 
     /**
-     * Join all arguments together and normalize the resulting path.
+     * Determines whether {path} is an absolute path. An absolute path will always resolve to the same location, regardless of the working directory.
      *
-     * @param paths paths to join.
+     * @param path path to test.
      */
-    join(...paths: string[]): string;
+    isAbsolute(p: string): boolean;
 
     /**
-     * Normalize a string path, reducing '..' and '.' parts.
-     * When multiple slashes are found, they're replaced by a single one;
-     * when the path contains a trailing slash, it is preserved. On Windows backslashes are used.
+     * Solve the relative path from {from} to {to}.
+     * At times we have two absolute paths, and we need to derive the relative path from one to the other. This is actually the reverse transform of path.resolve.
+     */
+    relative(from: string, to: string): string;
+
+    /**
+     * Return the directory name of a path. Similar to the Unix dirname command.
      *
-     * @param path string path to normalize.
+     * @param p the path to evaluate.
      */
-    normalize(path: string): string;
+    dirname(p: string): string;
 
     /**
-     * The right-most parameter is considered {to}. Other parameters are considered an array of {from}.
-     * Starting from leftmost {from} paramter, resolves {to} to an absolute path.
+     * Return the last portion of a path. Similar to the Unix basename command.
+     * Often used to extract the file name from a fully qualified path.
      *
-     * If {to} isn't already absolute, {from} arguments are prepended in right to left order,
-     * until an absolute path is found.
-     * If after using all {from} paths still no absolute path is found, the current working directory is used as well.
-     * The resulting path is normalized, and trailing slashes are removed unless the path gets resolved to the
-     * root directory.
+     * @param p the path to evaluate.
+     * @param ext optionally, an extension to remove from the result.
+     */
+    basename(p: string, ext?: string): string;
+
+    /**
+     * Return the extension of the path, from the last '.' to end of string in the last portion of the path.
+     * If there is no '.' in the last portion of the path or the first character of it is '.', then it returns an empty string
      *
-     * @param pathSegments string paths to join.
+     * @param p the path to evaluate.
      */
+    extname(p: string): string;
 
-    resolve(...pathSegments: string[]): string;
+    /**
+     * Returns an object from a path string - the opposite of format().
+     *
+     * @param pathString path to evaluate.
+     */
+    parse(p: string): IParsedPath;
 
     /**
-     * Solve the relative path from {from} to {to}.
-     * At times we have two absolute paths, and we need to derive the relative path from one to the other.
-     * This is actually the reverse transform of resolve().
+     * Returns a path string from an object - the opposite of parse().
      */
-    relative(from: string, to: string): string;
+    format(pP: IFormatInputPathObject): string;
 
     /**
-     * Determines whether {path} is an absolute path.
-     * An absolute path will always resolve to the same location, regardless of the working directory.
-     *
-     * @param path path to test.
+     * Posix specific pathing.
+     * Same as parent object on posix.
      */
-    isAbsolute(path: string): boolean;
+    readonly posix: IFileSystemPath;
+
+    /**
+     * Windows specific pathing.
+     * Same as parent object on windows
+     */
+    readonly win32: IFileSystemPath;
 }
+
+/**
+ * A parsed path object generated by path.parse() or consumed by path.format().
+ */
+export interface IParsedPath {
+    /**
+     * The root of the path such as '/' or 'c:\'
+     */
+    root: string;
+
+    /**
+     * The full directory path such as '/home/user/dir' or 'c:\path\dir'
+     */
+    dir: string;
+
+    /**
+     * The file name including extension (if any) such as 'index.html'
+     */
+    base: string;
+
+    /**
+     * The file extension (if any) such as '.html'
+     */
+    ext: string;
+
+    /**
+     * The file name without extension (if any) such as 'index'
+     */
+    name: string;
+}
+
+export interface IFormatInputPathObject {
+    /**
+     * The root of the path such as '/' or 'c:\'
+     */
+    root?: string;
+
+    /**
+     * The full directory path such as '/home/user/dir' or 'c:\path\dir'
+     */
+    dir?: string;
+
+    /**
+     * The file name including extension (if any) such as 'index.html'
+     */
+    base?: string;
+
+    /**
+     * The file extension (if any) such as '.html'
+     */
+    ext?: string;
+
+    /**
+     * The file name without extension (if any) such as 'index'
+     */
+    name?: string;
+}

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

71411

increased by6.32%

Lines of code

1525

increased by9.16%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes