@guanghechen/path 1.0.0-alpha.3 → 1.0.0-alpha.5

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.5](https://github.com/guanghechen/sora/compare/@guanghechen/path@1.0.0-alpha.4...@guanghechen/path@1.0.0-alpha.5) (2023-10-16)
+
+
+### Performance Improvements
+
+* :art:  refactor @guanghechen/path and @guanghechen/filepath ([5952ac3](https://github.com/guanghechen/sora/commit/5952ac39fee92e807e3cccc8e4b4dfa1aba1fa34))
+* 🔧 remove unnecessary devDependencies ([944f3ae](https://github.com/guanghechen/sora/commit/944f3aee64e68ce52ca30237c7d0240a82c9c58f))
+
+
+
+
+
+# [1.0.0-alpha.4](https://github.com/guanghechen/sora/compare/@guanghechen/path@1.0.0-alpha.3...@guanghechen/path@1.0.0-alpha.4) (2023-10-10)
+
+**Note:** Version bump only for package @guanghechen/path
+
+
+
+
+
 # [1.0.0-alpha.3](https://github.com/guanghechen/sora/compare/@guanghechen/path@1.0.0-alpha.2...@guanghechen/path@1.0.0-alpha.3) (2023-10-09)
 
 

package/lib/cjs/index.cjs

@@ -1,13 +1,15 @@
 'use strict';
 
 var path = require('node:path');
+var node_fs = require('node:fs');
+var node_url = require('node:url');
 var path_types = require('@guanghechen/path.types');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var path__default = /*#__PURE__*/_interopDefault(path);
 
-const clazz$2 = 'PhysicalPathResolver';
+const clazz$1 = 'PhysicalPathResolver';
 class PhysicalPathResolver {
     basename(filepath) {
         this.ensureAbsolute(filepath);
@@ -17,7 +19,12 @@ class PhysicalPathResolver {
     ensureAbsolute(filepath, message) {
         if (this.isAbsolute(filepath))
             return;
-        throw new Error(message ?? `[${clazz$2}] not an absolute path: ${filepath}.`);
+        throw new Error(message ?? `[${clazz$1}] not an absolute path: ${filepath}.`);
+    }
+    ensureSafeRelative(root, filepath, message) {
+        if (this.isSafeRelative(root, filepath))
+            return;
+        throw new Error(message ?? `[${clazz$1}] not under the root path: filepath ${filepath}, root: ${root}.`);
     }
     dirname(filepath) {
         this.ensureAbsolute(filepath);
@@ -27,11 +34,17 @@ class PhysicalPathResolver {
     isAbsolute(filepath) {
         return path__default.default.isAbsolute(filepath);
     }
+    isSafeRelative(root, filepath) {
+        if (!this.isAbsolute(root))
+            return false;
+        const relativePath = this._internalSafeRelative(root, filepath);
+        return !relativePath.startsWith('..');
+    }
     join(filepath, ...pathPieces) {
-        this.ensureAbsolute(filepath, `[${clazz$2}.join] not an absolute path: ${filepath}.`);
+        this.ensureAbsolute(filepath, `[${clazz$1}.join] not an absolute path: ${filepath}.`);
         for (const pathPiece of pathPieces) {
             if (this.isAbsolute(pathPiece)) {
-                throw new Error(`[${clazz$2}.join] pathPiece shouldn't be absolute path. ${pathPiece}`);
+                throw new Error(`[${clazz$1}.join] pathPiece shouldn't be absolute path. ${pathPiece}`);
             }
         }
         const p = path__default.default.join(filepath, ...pathPieces);
@@ -39,62 +52,43 @@ class PhysicalPathResolver {
     }
     normalize(filepath) {
         this.ensureAbsolute(filepath);
+        return this._internalNormalize(filepath);
+    }
+    relative(from, to) {
+        this.ensureAbsolute(from, `[${clazz$1}.relative] from is not an absolute path: ${from}`);
+        this.ensureAbsolute(to, `[${clazz$1}.relative] to is not an absolute path: ${to}`);
+        return this._internalRelative(from, to);
+    }
+    safeRelative(root, filepath) {
+        this.ensureSafeRelative(root, filepath);
+        return this._internalSafeRelative(root, filepath);
+    }
+    safeResolve(root, filepath) {
+        this.ensureSafeRelative(root, filepath);
+        return this._internalSafeResolve(root, filepath);
+    }
+    _internalNormalize(filepath) {
         const p = path__default.default
             .normalize(filepath)
             .replace(/[/\\]+/g, path__default.default.sep)
             .replace(/[/\\]+$/, '');
         return p.length <= 0 ? '/' : p;
     }
-    relative(from_, to_) {
-        this.ensureAbsolute(from_, `[${clazz$2}.relative] from is not an absolute path: ${from_}`);
-        this.ensureAbsolute(to_, `[${clazz$2}.relative] to is not an absolute path: ${to_}`);
+    _internalRelative(from_, to_) {
         const from = this.normalize(from_);
         const to = this.normalize(to_);
         const relativePath = path__default.default.relative(from, to);
         return relativePath;
     }
-}
-
-const clazz$1 = 'WorkspacePathResolver';
-class WorkspacePathResolver {
-    root;
-    pathResolver;
-    constructor(root, pathResolver) {
-        this.root = root;
-        this.pathResolver = pathResolver;
-    }
-    ensureSafePath(filepath, message) {
-        if (this.isSafePath(filepath))
-            return;
-        throw new Error(message ?? `[${clazz$1}] not an absolute path: ${filepath}.`);
-    }
-    isSafePath(filepath) {
-        const { root, pathResolver } = this;
-        if (!pathResolver.isAbsolute(filepath))
-            return true;
-        if (filepath === root)
-            return true;
-        const relativePath = pathResolver.relative(root, filepath);
-        return !relativePath.startsWith('..');
-    }
-    resolve(filepath) {
-        this.ensureSafePath(filepath);
-        const { root, pathResolver } = this;
-        if (pathResolver.isAbsolute(filepath))
-            return pathResolver.normalize(filepath);
-        return pathResolver.join(root, filepath);
+    _internalSafeRelative(root_, filepath_) {
+        const root = this._internalNormalize(root_);
+        const filepath = this._internalSafeResolve(root, filepath_);
+        const relativePath = this._internalRelative(root, filepath);
+        return relativePath;
     }
-    relative(filepath_) {
-        this.ensureSafePath(filepath_);
-        const filepath = this.resolve(filepath_);
-        return this.pathResolver.relative(this.root, filepath);
-    }
-}
-
-class PhysicalWorkspacePathResolver extends WorkspacePathResolver {
-    constructor(root) {
-        const pathResolver = new PhysicalPathResolver();
-        super(root, pathResolver);
+    _internalSafeResolve(root, filepath_) {
+        const filepath = this.isAbsolute(filepath_) ? filepath_ : path__default.default.join(root, filepath_);
+        return this._internalNormalize(filepath);
     }
 }
 
@@ -111,6 +105,11 @@ class VirtualPathResolver {
             return;
         throw new Error(message ?? `[${clazz}] not an absolute path: ${filepath}.`);
     }
+    ensureSafeRelative(root, filepath, message) {
+        if (this.isSafeRelative(root, filepath))
+            return;
+        throw new Error(message ?? `[${clazz}] not under the root path: filepath ${filepath}, root: ${root}.`);
+    }
     dirname(filepath) {
         this.ensureAbsolute(filepath);
         const p = this.normalize(filepath);
@@ -120,6 +119,12 @@ class VirtualPathResolver {
     isAbsolute(filepath) {
         return filepath.startsWith('/') || filepath.startsWith('\\');
     }
+    isSafeRelative(root, filepath) {
+        if (!this.isAbsolute(root))
+            return false;
+        const relativePath = this._internalSafeRelative(root, filepath);
+        return !relativePath.startsWith('..');
+    }
     join(filepath, ...pathPieces) {
         this.ensureAbsolute(filepath, `[${clazz}.join] not an absolute path: ${filepath}.`);
         for (const pathPiece of pathPieces) {
@@ -127,11 +132,30 @@ class VirtualPathResolver {
                 throw new Error(`[${clazz}.join] pathPiece shouldn't be absolute path. ${pathPiece}`);
             }
         }
-        const p = filepath + '/' + pathPieces.join('/');
-        return this.normalize(p);
+        return this._internalJoin(filepath, pathPieces.join('/'));
     }
     normalize(filepath) {
         this.ensureAbsolute(filepath);
+        return this._internalNormalize(filepath);
+    }
+    relative(from, to) {
+        this.ensureAbsolute(from, `[${clazz}.relative] from is not an absolute path: ${from}`);
+        this.ensureAbsolute(to, `[${clazz}.relative] to is not an absolute path: ${to}`);
+        return this._internalRelative(from, to);
+    }
+    safeRelative(root, filepath) {
+        this.ensureSafeRelative(root, filepath);
+        return this._internalSafeRelative(root, filepath);
+    }
+    safeResolve(root, filepath) {
+        this.ensureSafeRelative(root, filepath);
+        return this._internalSafeResolve(root, filepath);
+    }
+    _internalJoin(root, relativePath) {
+        const filepath = root + '/' + relativePath;
+        return this._internalNormalize(filepath);
+    }
+    _internalNormalize(filepath) {
         const pieces = [];
         for (const piece of filepath.split(/[/\\]+/g)) {
             if (!piece)
@@ -146,9 +170,7 @@ class VirtualPathResolver {
         }
         return '/' + pieces.join('/');
     }
-    relative(from_, to_) {
-        this.ensureAbsolute(from_, `[${clazz}.relative] from is not an absolute path: ${from_}`);
-        this.ensureAbsolute(to_, `[${clazz}.relative] to is not an absolute path: ${to_}`);
+    _internalRelative(from_, to_) {
         const from = this.normalize(from_);
         const to = this.normalize(to_);
         const fromPieces = from.split('/');
@@ -161,6 +183,78 @@ class VirtualPathResolver {
         }
         return '../'.repeat(fromPieces.length - ci) + toPieces.slice(ci).join('/');
     }
+    _internalSafeRelative(root_, filepath_) {
+        const root = this._internalNormalize(root_);
+        const filepath = this._internalSafeResolve(root, filepath_);
+        const relativePath = this._internalRelative(root, filepath);
+        return relativePath;
+    }
+    _internalSafeResolve(root, filepath_) {
+        const filepath = this.isAbsolute(filepath_) ? filepath_ : this.join(root, filepath_);
+        return filepath;
+    }
+}
+
+function locateNearestFilepath(currentDir, filenames) {
+    return internalRecursiveLocate(currentDir.startsWith('file://') ? node_url.fileURLToPath(currentDir) : currentDir, [filenames].flat());
+}
+function findNearestFilepath(currentDir, predicate) {
+    return internalFindNearestFilepath(currentDir.startsWith('file://') ? node_url.fileURLToPath(currentDir) : currentDir, predicate);
+}
+function internalRecursiveLocate(currentDir, filenames) {
+    for (const filename of filenames) {
+        const filepath = path.join(currentDir, filename);
+        if (node_fs.existsSync(filepath))
+            return filepath;
+    }
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir || !path.isAbsolute(parentDir))
+        return null;
+    return locateNearestFilepath(parentDir, filenames);
+}
+function internalFindNearestFilepath(currentDir, predicate) {
+    const filenames = node_fs.readdirSync(currentDir);
+    for (const filename of filenames) {
+        const filepath = path.join(currentDir, filename);
+        if (predicate(filepath))
+            return filepath;
+    }
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir)
+        return null;
+    return internalFindNearestFilepath(parentDir, predicate);
+}
+
+class WorkspacePathResolver {
+    root;
+    pathResolver;
+    constructor(root, pathResolver) {
+        this.root = root;
+        this.pathResolver = pathResolver;
+    }
+    ensureSafePath(filepath, message) {
+        const { root, pathResolver } = this;
+        pathResolver.ensureSafeRelative(root, filepath, message);
+    }
+    isSafePath(filepath) {
+        const { root, pathResolver } = this;
+        return pathResolver.isSafeRelative(root, filepath);
+    }
+    relative(filepath) {
+        const { root, pathResolver } = this;
+        return pathResolver.safeRelative(root, filepath);
+    }
+    resolve(filepath) {
+        const { root, pathResolver } = this;
+        return pathResolver.safeResolve(root, filepath);
+    }
+}
+
+class PhysicalWorkspacePathResolver extends WorkspacePathResolver {
+    constructor(root) {
+        const pathResolver = new PhysicalPathResolver();
+        super(root, pathResolver);
+    }
 }
 
 class VirtualWorkspacePathResolver extends WorkspacePathResolver {
@@ -170,11 +264,18 @@ class VirtualWorkspacePathResolver extends WorkspacePathResolver {
     }
 }
 
+const physicalPathResolver = new PhysicalPathResolver();
+const virtualPathResolver = new VirtualPathResolver();
+
 exports.PhysicalPathResolver = PhysicalPathResolver;
 exports.PhysicalWorkspacePathResolver = PhysicalWorkspacePathResolver;
 exports.VirtualPathResolver = VirtualPathResolver;
 exports.VirtualWorkspacePathResolver = VirtualWorkspacePathResolver;
 exports.WorkspacePathResolver = WorkspacePathResolver;
+exports.findNearestFilepath = findNearestFilepath;
+exports.locateNearestFilepath = locateNearestFilepath;
+exports.physicalPathResolver = physicalPathResolver;
+exports.virtualPathResolver = virtualPathResolver;
 Object.keys(path_types).forEach(function (k) {
     if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
         enumerable: true,

package/lib/esm/index.mjs

@@ -1,7 +1,9 @@
-import path from 'node:path';
+import path, { join, dirname, isAbsolute } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 export * from '@guanghechen/path.types';
 
-const clazz$2 = 'PhysicalPathResolver';
+const clazz$1 = 'PhysicalPathResolver';
 class PhysicalPathResolver {
     basename(filepath) {
         this.ensureAbsolute(filepath);
@@ -11,7 +13,12 @@ class PhysicalPathResolver {
     ensureAbsolute(filepath, message) {
         if (this.isAbsolute(filepath))
             return;
-        throw new Error(message ?? `[${clazz$2}] not an absolute path: ${filepath}.`);
+        throw new Error(message ?? `[${clazz$1}] not an absolute path: ${filepath}.`);
+    }
+    ensureSafeRelative(root, filepath, message) {
+        if (this.isSafeRelative(root, filepath))
+            return;
+        throw new Error(message ?? `[${clazz$1}] not under the root path: filepath ${filepath}, root: ${root}.`);
     }
     dirname(filepath) {
         this.ensureAbsolute(filepath);
@@ -21,11 +28,17 @@ class PhysicalPathResolver {
     isAbsolute(filepath) {
         return path.isAbsolute(filepath);
     }
+    isSafeRelative(root, filepath) {
+        if (!this.isAbsolute(root))
+            return false;
+        const relativePath = this._internalSafeRelative(root, filepath);
+        return !relativePath.startsWith('..');
+    }
     join(filepath, ...pathPieces) {
-        this.ensureAbsolute(filepath, `[${clazz$2}.join] not an absolute path: ${filepath}.`);
+        this.ensureAbsolute(filepath, `[${clazz$1}.join] not an absolute path: ${filepath}.`);
         for (const pathPiece of pathPieces) {
             if (this.isAbsolute(pathPiece)) {
-                throw new Error(`[${clazz$2}.join] pathPiece shouldn't be absolute path. ${pathPiece}`);
+                throw new Error(`[${clazz$1}.join] pathPiece shouldn't be absolute path. ${pathPiece}`);
             }
         }
         const p = path.join(filepath, ...pathPieces);
@@ -33,62 +46,43 @@ class PhysicalPathResolver {
     }
     normalize(filepath) {
         this.ensureAbsolute(filepath);
+        return this._internalNormalize(filepath);
+    }
+    relative(from, to) {
+        this.ensureAbsolute(from, `[${clazz$1}.relative] from is not an absolute path: ${from}`);
+        this.ensureAbsolute(to, `[${clazz$1}.relative] to is not an absolute path: ${to}`);
+        return this._internalRelative(from, to);
+    }
+    safeRelative(root, filepath) {
+        this.ensureSafeRelative(root, filepath);
+        return this._internalSafeRelative(root, filepath);
+    }
+    safeResolve(root, filepath) {
+        this.ensureSafeRelative(root, filepath);
+        return this._internalSafeResolve(root, filepath);
+    }
+    _internalNormalize(filepath) {
         const p = path
             .normalize(filepath)
             .replace(/[/\\]+/g, path.sep)
             .replace(/[/\\]+$/, '');
         return p.length <= 0 ? '/' : p;
     }
-    relative(from_, to_) {
-        this.ensureAbsolute(from_, `[${clazz$2}.relative] from is not an absolute path: ${from_}`);
-        this.ensureAbsolute(to_, `[${clazz$2}.relative] to is not an absolute path: ${to_}`);
+    _internalRelative(from_, to_) {
         const from = this.normalize(from_);
         const to = this.normalize(to_);
         const relativePath = path.relative(from, to);
         return relativePath;
     }
-}
-
-const clazz$1 = 'WorkspacePathResolver';
-class WorkspacePathResolver {
-    root;
-    pathResolver;
-    constructor(root, pathResolver) {
-        this.root = root;
-        this.pathResolver = pathResolver;
-    }
-    ensureSafePath(filepath, message) {
-        if (this.isSafePath(filepath))
-            return;
-        throw new Error(message ?? `[${clazz$1}] not an absolute path: ${filepath}.`);
-    }
-    isSafePath(filepath) {
-        const { root, pathResolver } = this;
-        if (!pathResolver.isAbsolute(filepath))
-            return true;
-        if (filepath === root)
-            return true;
-        const relativePath = pathResolver.relative(root, filepath);
-        return !relativePath.startsWith('..');
-    }
-    resolve(filepath) {
-        this.ensureSafePath(filepath);
-        const { root, pathResolver } = this;
-        if (pathResolver.isAbsolute(filepath))
-            return pathResolver.normalize(filepath);
-        return pathResolver.join(root, filepath);
+    _internalSafeRelative(root_, filepath_) {
+        const root = this._internalNormalize(root_);
+        const filepath = this._internalSafeResolve(root, filepath_);
+        const relativePath = this._internalRelative(root, filepath);
+        return relativePath;
     }
-    relative(filepath_) {
-        this.ensureSafePath(filepath_);
-        const filepath = this.resolve(filepath_);
-        return this.pathResolver.relative(this.root, filepath);
-    }
-}
-
-class PhysicalWorkspacePathResolver extends WorkspacePathResolver {
-    constructor(root) {
-        const pathResolver = new PhysicalPathResolver();
-        super(root, pathResolver);
+    _internalSafeResolve(root, filepath_) {
+        const filepath = this.isAbsolute(filepath_) ? filepath_ : path.join(root, filepath_);
+        return this._internalNormalize(filepath);
     }
 }
 
@@ -105,6 +99,11 @@ class VirtualPathResolver {
             return;
         throw new Error(message ?? `[${clazz}] not an absolute path: ${filepath}.`);
     }
+    ensureSafeRelative(root, filepath, message) {
+        if (this.isSafeRelative(root, filepath))
+            return;
+        throw new Error(message ?? `[${clazz}] not under the root path: filepath ${filepath}, root: ${root}.`);
+    }
     dirname(filepath) {
         this.ensureAbsolute(filepath);
         const p = this.normalize(filepath);
@@ -114,6 +113,12 @@ class VirtualPathResolver {
     isAbsolute(filepath) {
         return filepath.startsWith('/') || filepath.startsWith('\\');
     }
+    isSafeRelative(root, filepath) {
+        if (!this.isAbsolute(root))
+            return false;
+        const relativePath = this._internalSafeRelative(root, filepath);
+        return !relativePath.startsWith('..');
+    }
     join(filepath, ...pathPieces) {
         this.ensureAbsolute(filepath, `[${clazz}.join] not an absolute path: ${filepath}.`);
         for (const pathPiece of pathPieces) {
@@ -121,11 +126,30 @@ class VirtualPathResolver {
                 throw new Error(`[${clazz}.join] pathPiece shouldn't be absolute path. ${pathPiece}`);
             }
         }
-        const p = filepath + '/' + pathPieces.join('/');
-        return this.normalize(p);
+        return this._internalJoin(filepath, pathPieces.join('/'));
     }
     normalize(filepath) {
         this.ensureAbsolute(filepath);
+        return this._internalNormalize(filepath);
+    }
+    relative(from, to) {
+        this.ensureAbsolute(from, `[${clazz}.relative] from is not an absolute path: ${from}`);
+        this.ensureAbsolute(to, `[${clazz}.relative] to is not an absolute path: ${to}`);
+        return this._internalRelative(from, to);
+    }
+    safeRelative(root, filepath) {
+        this.ensureSafeRelative(root, filepath);
+        return this._internalSafeRelative(root, filepath);
+    }
+    safeResolve(root, filepath) {
+        this.ensureSafeRelative(root, filepath);
+        return this._internalSafeResolve(root, filepath);
+    }
+    _internalJoin(root, relativePath) {
+        const filepath = root + '/' + relativePath;
+        return this._internalNormalize(filepath);
+    }
+    _internalNormalize(filepath) {
         const pieces = [];
         for (const piece of filepath.split(/[/\\]+/g)) {
             if (!piece)
@@ -140,9 +164,7 @@ class VirtualPathResolver {
         }
         return '/' + pieces.join('/');
     }
-    relative(from_, to_) {
-        this.ensureAbsolute(from_, `[${clazz}.relative] from is not an absolute path: ${from_}`);
-        this.ensureAbsolute(to_, `[${clazz}.relative] to is not an absolute path: ${to_}`);
+    _internalRelative(from_, to_) {
         const from = this.normalize(from_);
         const to = this.normalize(to_);
         const fromPieces = from.split('/');
@@ -155,6 +177,78 @@ class VirtualPathResolver {
         }
         return '../'.repeat(fromPieces.length - ci) + toPieces.slice(ci).join('/');
     }
+    _internalSafeRelative(root_, filepath_) {
+        const root = this._internalNormalize(root_);
+        const filepath = this._internalSafeResolve(root, filepath_);
+        const relativePath = this._internalRelative(root, filepath);
+        return relativePath;
+    }
+    _internalSafeResolve(root, filepath_) {
+        const filepath = this.isAbsolute(filepath_) ? filepath_ : this.join(root, filepath_);
+        return filepath;
+    }
+}
+
+function locateNearestFilepath(currentDir, filenames) {
+    return internalRecursiveLocate(currentDir.startsWith('file://') ? fileURLToPath(currentDir) : currentDir, [filenames].flat());
+}
+function findNearestFilepath(currentDir, predicate) {
+    return internalFindNearestFilepath(currentDir.startsWith('file://') ? fileURLToPath(currentDir) : currentDir, predicate);
+}
+function internalRecursiveLocate(currentDir, filenames) {
+    for (const filename of filenames) {
+        const filepath = join(currentDir, filename);
+        if (existsSync(filepath))
+            return filepath;
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir || !isAbsolute(parentDir))
+        return null;
+    return locateNearestFilepath(parentDir, filenames);
+}
+function internalFindNearestFilepath(currentDir, predicate) {
+    const filenames = readdirSync(currentDir);
+    for (const filename of filenames) {
+        const filepath = join(currentDir, filename);
+        if (predicate(filepath))
+            return filepath;
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir)
+        return null;
+    return internalFindNearestFilepath(parentDir, predicate);
+}
+
+class WorkspacePathResolver {
+    root;
+    pathResolver;
+    constructor(root, pathResolver) {
+        this.root = root;
+        this.pathResolver = pathResolver;
+    }
+    ensureSafePath(filepath, message) {
+        const { root, pathResolver } = this;
+        pathResolver.ensureSafeRelative(root, filepath, message);
+    }
+    isSafePath(filepath) {
+        const { root, pathResolver } = this;
+        return pathResolver.isSafeRelative(root, filepath);
+    }
+    relative(filepath) {
+        const { root, pathResolver } = this;
+        return pathResolver.safeRelative(root, filepath);
+    }
+    resolve(filepath) {
+        const { root, pathResolver } = this;
+        return pathResolver.safeResolve(root, filepath);
+    }
+}
+
+class PhysicalWorkspacePathResolver extends WorkspacePathResolver {
+    constructor(root) {
+        const pathResolver = new PhysicalPathResolver();
+        super(root, pathResolver);
+    }
 }
 
 class VirtualWorkspacePathResolver extends WorkspacePathResolver {
@@ -164,4 +258,7 @@ class VirtualWorkspacePathResolver extends WorkspacePathResolver {
     }
 }
 
-export { PhysicalPathResolver, PhysicalWorkspacePathResolver, VirtualPathResolver, VirtualWorkspacePathResolver, WorkspacePathResolver };
+const physicalPathResolver = new PhysicalPathResolver();
+const virtualPathResolver = new VirtualPathResolver();
+
+export { PhysicalPathResolver, PhysicalWorkspacePathResolver, VirtualPathResolver, VirtualWorkspacePathResolver, WorkspacePathResolver, findNearestFilepath, locateNearestFilepath, physicalPathResolver, virtualPathResolver };

package/lib/types/index.d.ts

@@ -1,14 +1,39 @@
 import { IPathResolver, IWorkspacePathResolver } from '@guanghechen/path.types';
 export * from '@guanghechen/path.types';
 
+/**
+ * Locate a nearest filepath from the given `currentDir` which name included in the give `filenames`.
+ *
+ * @param currentDir
+ * @param filenames
+ * @returns
+ */
+declare function locateNearestFilepath(currentDir: string, filenames: string | ReadonlyArray<string>): string | null;
+/**
+ * Find a nearest filepath from the give `currentDir`which matched the give tester `testFilepath`.
+ *
+ * @param currentDir
+ * @param predicate
+ * @returns
+ */
+declare function findNearestFilepath(currentDir: string, predicate: (filepath: string) => boolean): string | null;
+
 declare class PhysicalPathResolver implements IPathResolver {
     basename(filepath: string): string;
     ensureAbsolute(filepath: string, message?: string | undefined): void | never;
+    ensureSafeRelative(root: string, filepath: string, message?: string | undefined): void | never;
     dirname(filepath: string): string | never;
     isAbsolute(filepath: string): boolean;
+    isSafeRelative(root: string, filepath: string): boolean;
     join(filepath: string, ...pathPieces: string[]): string | never;
     normalize(filepath: string): string | never;
-    relative(from_: string, to_: string): string | never;
+    relative(from: string, to: string): string | never;
+    safeRelative(root: string, filepath: string): string;
+    safeResolve(root: string, filepath: string): string;
+    protected _internalNormalize(filepath: string): string;
+    protected _internalRelative(from_: string, to_: string): string;
+    protected _internalSafeRelative(root_: string, filepath_: string): string;
+    protected _internalSafeResolve(root: string, filepath_: string): string;
 }
 
 declare class WorkspacePathResolver implements IWorkspacePathResolver {
@@ -17,8 +42,8 @@ declare class WorkspacePathResolver implements IWorkspacePathResolver {
     constructor(root: string, pathResolver: IPathResolver);
     ensureSafePath(filepath: string, message?: string | undefined): void | never;
     isSafePath(filepath: string): boolean;
+    relative(filepath: string): string | never;
     resolve(filepath: string): string | never;
-    relative(filepath_: string): string | never;
 }
 
 declare class PhysicalWorkspacePathResolver extends WorkspacePathResolver implements IWorkspacePathResolver {
@@ -28,15 +53,27 @@ declare class PhysicalWorkspacePathResolver extends WorkspacePathResolver implem
 declare class VirtualPathResolver implements IPathResolver {
     basename(filepath: string): string;
     ensureAbsolute(filepath: string, message?: string | undefined): void | never;
+    ensureSafeRelative(root: string, filepath: string, message?: string | undefined): void;
     dirname(filepath: string): string | never;
     isAbsolute(filepath: string): boolean;
+    isSafeRelative(root: string, filepath: string): boolean;
     join(filepath: string, ...pathPieces: string[]): string | never;
     normalize(filepath: string): string | never;
-    relative(from_: string, to_: string): string | never;
+    relative(from: string, to: string): string | never;
+    safeRelative(root: string, filepath: string): string;
+    safeResolve(root: string, filepath: string): string;
+    protected _internalJoin(root: string, relativePath: string): string;
+    protected _internalNormalize(filepath: string): string;
+    protected _internalRelative(from_: string, to_: string): string;
+    protected _internalSafeRelative(root_: string, filepath_: string): string;
+    protected _internalSafeResolve(root: string, filepath_: string): string;
 }
 
 declare class VirtualWorkspacePathResolver extends WorkspacePathResolver implements IWorkspacePathResolver {
     constructor(root: string);
 }
 
-export { PhysicalPathResolver, PhysicalWorkspacePathResolver, VirtualPathResolver, VirtualWorkspacePathResolver, WorkspacePathResolver };
+declare const physicalPathResolver: IPathResolver;
+declare const virtualPathResolver: IPathResolver;
+
+export { PhysicalPathResolver, PhysicalWorkspacePathResolver, VirtualPathResolver, VirtualWorkspacePathResolver, WorkspacePathResolver, findNearestFilepath, locateNearestFilepath, physicalPathResolver, virtualPathResolver };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/path",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.5",
   "description": "Path utils.",
   "author": {
     "name": "guanghechen",
@@ -8,10 +8,10 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/guanghechen/sora/tree/@guanghechen/path@1.0.0-alpha.2",
+    "url": "https://github.com/guanghechen/sora/tree/@guanghechen/path@1.0.0-alpha.4",
     "directory": "packages/path"
   },
-  "homepage": "https://github.com/guanghechen/sora/tree/@guanghechen/path@1.0.0-alpha.2/packages/path#readme",
+  "homepage": "https://github.com/guanghechen/sora/tree/@guanghechen/path@1.0.0-alpha.4/packages/path#readme",
   "type": "module",
   "exports": {
     ".": {
@@ -38,17 +38,12 @@
     "README.md"
   ],
   "scripts": {
-    "build": "rimraf lib/ && cross-env NODE_ENV=production rollup -c ../../rollup.config.mjs",
+    "build": "../../node_modules/.bin/rimraf lib/ && ../../node_modules/.bin/cross-env NODE_ENV=production ../../node_modules/.bin/rollup -c ../../rollup.config.mjs",
     "prepublishOnly": "yarn build",
     "test": "node --experimental-vm-modules ../../node_modules/.bin/jest --config ../../jest.config.mjs --rootDir ."
   },
   "dependencies": {
-    "@guanghechen/path.types": "^1.0.0-alpha.2"
+    "@guanghechen/path.types": "^1.0.0-alpha.4"
   },
-  "devDependencies": {
-    "cross-env": "*",
-    "rimraf": "*",
-    "rollup": "*"
-  },
-  "gitHead": "283e59d85998ff630abddc0224f6dd2bf9546ca2"
+  "gitHead": "5970cec8f9021212fd2009f40f65f0abf5ba77ec"
 }