nice-path 2.0.0 → 3.0.0

package/README.md

@@ -2,6 +2,8 @@
 
 `nice-path` provides a class that represents a filesystem path (POSIX-style or Win32-style), which has various nice methods on it that make it easy to work with. It can be used as a replacement for the Node.js `path` builtin module, where you pass around Path objects and stringify them before use, rather than passing around strings.
 
+> `nice-path`'s code is derived from [yavascript](https://github.com/suchipi/yavascript).
+
 ## Example
 
 ```ts
@@ -192,6 +194,8 @@ The `isAbsolute` method returns whether the target Path is an absolute path; tha
 
 The `clone` method makes a second Path object containing the same segments and separator as the target.
 
+Note that although the new Path has the same segments as the target Path, it doesn't use the same Array instance.
+
 #### `relativeTo(dir, options?): Path` (instance method of Path)
 
 The `relativeTo` method expresses the target path as a relative path, relative to the `dir` argument.

package/dist/index.d.ts

@@ -34,8 +34,21 @@ export declare class Path {
     separator: string;
     /** Create a new Path object using the provided input(s). */
     constructor(...inputs: Array<string | Path | Array<string | Path>>);
+    /**
+     * Create a new Path object using the provided segments and, optionally,
+     * separator.
+     *
+     * NOTE: this doesn't set the `segments` directly; it passes them through a
+     * filtering step first, to remove any double-slashes or etc. To set the
+     * `.segments` directly, use {@link fromRaw}.
+     */
+    static from(segments: Array<string>, separator?: string): Path;
     /**
      * Create a new Path object using the provided segments and separator.
+     *
+     * NOTE: this method doesn't do any sort of validation on `segments`; as such,
+     * it can be used to construct an invalid Path object. Consider using
+     * {@link from} instead.
      */
     static fromRaw(segments: Array<string>, separator: string): Path;
     /**
@@ -147,6 +160,8 @@ export declare class Path {
      *
      * @param value - What should be replaced
      * @param replacement - What it should be replaced with
+     *
+     * NOTE: to remove segments, use an empty Array for `replacement`.
      */
     replace(value: string | Path | Array<string | Path>, replacement: string | Path | Array<string | Path>): Path;
     /**

package/dist/index.js

@@ -79,12 +79,31 @@ class Path {
         this.segments = Path.splitToSegments(parts);
         this.separator = Path.detectSeparator(parts, "/");
     }
+    /**
+     * Create a new Path object using the provided segments and, optionally,
+     * separator.
+     *
+     * NOTE: this doesn't set the `segments` directly; it passes them through a
+     * filtering step first, to remove any double-slashes or etc. To set the
+     * `.segments` directly, use {@link fromRaw}.
+     */
+    static from(segments, separator) {
+        const separatorToUse = separator || Path.detectSeparator(segments, "/");
+        const path = new Path();
+        path.segments = validateSegments(segments, separatorToUse);
+        path.separator = separatorToUse;
+        return path;
+    }
     /**
      * Create a new Path object using the provided segments and separator.
+     *
+     * NOTE: this method doesn't do any sort of validation on `segments`; as such,
+     * it can be used to construct an invalid Path object. Consider using
+     * {@link from} instead.
      */
     static fromRaw(segments, separator) {
         const path = new Path();
-        path.segments = validateSegments(segments, separator);
+        path.segments = segments;
         path.separator = separator;
         return path;
     }
@@ -132,7 +151,7 @@ class Path {
      */
     concat(...others) {
         const otherSegments = new Path(others.flat(1)).segments;
-        return Path.fromRaw(this.segments.concat(otherSegments), this.separator);
+        return Path.from(this.segments.concat(otherSegments), this.separator);
     }
     /**
      * Return whether this path is absolute; that is, whether it starts with
@@ -154,7 +173,7 @@ class Path {
      * this one.
      */
     clone() {
-        const theClone = this.constructor.fromRaw(this.segments, this.separator);
+        const theClone = this.constructor.fromRaw([...this.segments], this.separator);
         return theClone;
     }
     /**
@@ -175,15 +194,15 @@ class Path {
         }
         if (dirSegments.length === 0) {
             if (options.noLeadingDot) {
-                return Path.fromRaw(ownSegments, this.separator);
+                return Path.from(ownSegments, this.separator);
             }
             else {
-                return Path.fromRaw([".", ...ownSegments], this.separator);
+                return Path.from([".", ...ownSegments], this.separator);
             }
         }
         else {
             const dotDots = dirSegments.map((_) => "..");
-            return Path.fromRaw([...dotDots, ...ownSegments], this.separator);
+            return Path.from([...dotDots, ...ownSegments], this.separator);
         }
     }
     /**
@@ -314,6 +333,8 @@ class Path {
      *
      * @param value - What should be replaced
      * @param replacement - What it should be replaced with
+     *
+     * NOTE: to remove segments, use an empty Array for `replacement`.
      */
     replace(value, replacement) {
         value = new Path(value);
@@ -328,7 +349,7 @@ class Path {
                 ...replacement.segments,
                 ...this.segments.slice(matchIndex + value.segments.length),
             ];
-            return Path.fromRaw(newSegments, this.separator);
+            return Path.from(newSegments, this.separator);
         }
     }
     /**
@@ -366,7 +387,7 @@ class Path {
         const segments = [...this.segments];
         segments.pop();
         segments.push(...replacement.segments);
-        return Path.fromRaw(segments, this.separator);
+        return Path.from(segments, this.separator);
     }
 }
 exports.Path = Path;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nice-path",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "repository": {