@guanghechen/path 2.0.0 → 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present guanghechen (https://github.com/guanghechen)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -49,7 +49,8 @@
 </header>
 <br/>
 
-Path utilities for file system operations and workspace path resolution.
+Path utilities for file system operations with safe path resolution and workspace management.
+Provides strict path validation to prevent directory traversal attacks.
 
 ## Install
 
@@ -67,5 +68,94 @@ Path utilities for file system operations and workspace path resolution.
 
 ## Usage
 
+### PathResolver
+
+Standard path resolver with safety checks:
+
+```typescript
+import { PathResolver, pathResolver } from '@guanghechen/path'
+
+// Use the default singleton
+pathResolver.normalize('/foo/bar/../baz') // '/foo/baz'
+pathResolver.basename('/foo/bar/file.txt') // 'file.txt'
+pathResolver.dirname('/foo/bar/file.txt') // '/foo/bar'
+pathResolver.join('/foo', 'bar', 'baz') // '/foo/bar/baz'
+pathResolver.relative('/foo/bar', '/foo/baz') // '../baz'
+
+// Check if path is within a root directory (safe from traversal)
+pathResolver.isSafeRelative('/workspace', '/workspace/src/file.ts') // true
+pathResolver.isSafeRelative('/workspace', '/etc/passwd') // false
+
+// Safe relative path (throws if unsafe)
+pathResolver.safeRelative('/workspace', '/workspace/src/file.ts') // 'src/file.ts'
+
+// Safe resolve (resolve relative path within root)
+pathResolver.safeResolve('/workspace', './src/file.ts') // '/workspace/src/file.ts'
+pathResolver.safeResolve('/workspace', '../outside') // throws Error
+
+// Create custom resolver with slash preference
+const resolver = new PathResolver({ preferSlash: true })
+resolver.relative('/foo/bar', '/foo/baz') // '../baz' (uses forward slashes on Windows)
+```
+
+### WorkspacePathResolver
+
+Workspace-scoped path operations:
+
+```typescript
+import { WorkspacePathResolver, pathResolver } from '@guanghechen/path'
+
+const workspace = new WorkspacePathResolver('/project/workspace', pathResolver)
+
+// Check if path is within workspace
+workspace.isSafePath('/project/workspace/src/index.ts') // true
+workspace.isSafePath('/etc/passwd') // false
+
+// Resolve relative paths within workspace
+workspace.resolve('./src/index.ts') // '/project/workspace/src/index.ts'
+workspace.resolve('package.json') // '/project/workspace/package.json'
+
+// Get relative path from workspace root
+workspace.relative('/project/workspace/src/index.ts') // 'src/index.ts'
+```
+
+### UrlPathResolver
+
+URL-style path resolution (forward slashes):
+
+```typescript
+import { UrlPathResolver, urlPathResolver } from '@guanghechen/path'
+
+urlPathResolver.normalize('/foo/bar/../baz') // '/foo/baz'
+urlPathResolver.join('/api', 'users', '123') // '/api/users/123'
+```
+
+### Locate Utilities
+
+Find files by traversing up the directory tree:
+
+```typescript
+import { locateNearestFilepath, findNearestFilepath } from '@guanghechen/path'
+
+// Find nearest file by name(s)
+const packageJson = locateNearestFilepath('/project/src/utils', 'package.json')
+// Returns: '/project/package.json' (if exists)
+
+// Find nearest file matching multiple names
+const config = locateNearestFilepath('/project/src', [
+  'tsconfig.json',
+  'jsconfig.json',
+])
+
+// Find nearest file with custom predicate
+const readme = findNearestFilepath('/project/src', (filepath) => {
+  return filepath.toLowerCase().endsWith('readme.md')
+})
+```
+
+## Reference
+
+- [homepage][homepage]
+
 [homepage]:
-  https://github.com/guanghechen/sora/tree/@guanghechen/path@2.0.0/packages/path#readme
+  https://github.com/guanghechen/sora/tree/@guanghechen/path@2.0.0/packages/path#readme

package/lib/cjs/index.cjs

@@ -3,11 +3,6 @@
 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$1 = 'PathResolver';
 class PathResolver {
@@ -18,7 +13,7 @@ class PathResolver {
     basename(filepath) {
         this.ensureAbsolute(filepath);
         const p = this.normalize(filepath);
-        return path__default.default.basename(p);
+        return path.basename(p);
     }
     ensureAbsolute(filepath, message) {
         if (this.isAbsolute(filepath))
@@ -32,11 +27,11 @@ class PathResolver {
     }
     dirname(filepath) {
         this.ensureAbsolute(filepath);
-        const p = path__default.default.dirname(filepath);
+        const p = path.dirname(filepath);
         return this.normalize(p);
     }
     isAbsolute(filepath) {
-        return path__default.default.isAbsolute(filepath);
+        return path.isAbsolute(filepath);
     }
     isSafeRelative(root, filepath) {
         if (!this.isAbsolute(root))
@@ -51,7 +46,7 @@ class PathResolver {
                 throw new Error(`[${clazz$1}.join] pathPiece shouldn't be absolute path. ${pathPiece}`);
             }
         }
-        const p = path__default.default.join(filepath, ...pathPieces);
+        const p = path.join(filepath, ...pathPieces);
         return this.normalize(p);
     }
     normalize(filepath) {
@@ -76,16 +71,16 @@ class PathResolver {
         return this._internalSafeResolve(root, filepath);
     }
     _internalNormalize(filepath) {
-        const p = path__default.default
+        const p = path
             .normalize(filepath)
-            .replace(/[/\\]+/g, path__default.default.sep)
+            .replace(/[/\\]+/g, path.sep)
             .replace(/[/\\]+$/, '');
         return p.length <= 0 ? '/' : p;
     }
     _internalRelative(from_, to_) {
         const from = this.normalize(from_);
         const to = this.normalize(to_);
-        const relativePath = path__default.default.relative(from, to);
+        const relativePath = path.relative(from, to);
         return relativePath;
     }
     _internalSafeRelative(root_, filepath_) {
@@ -95,7 +90,7 @@ class PathResolver {
         return relativePath;
     }
     _internalSafeResolve(root, filepath_) {
-        const filepath = this.isAbsolute(filepath_) ? filepath_ : path__default.default.join(root, filepath_);
+        const filepath = this.isAbsolute(filepath_) ? filepath_ : path.join(root, filepath_);
         return this._internalNormalize(filepath);
     }
 }
@@ -268,9 +263,3 @@ exports.findNearestFilepath = findNearestFilepath;
 exports.locateNearestFilepath = locateNearestFilepath;
 exports.pathResolver = pathResolver;
 exports.urlPathResolver = urlPathResolver;
-Object.keys(path_types).forEach(function (k) {
-    if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
-        enumerable: true,
-        get: function () { return path_types[k]; }
-    });
-});

package/lib/esm/index.mjs

@@ -1,7 +1,6 @@
 import path, { join, dirname, isAbsolute } from 'node:path';
 import { readdirSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-export * from '@guanghechen/path.types';
 
 const clazz$1 = 'PathResolver';
 class PathResolver {

package/lib/types/index.d.ts

@@ -1,5 +1,4 @@
-import { IPathResolver, IPathResolverParams, IWorkspacePathResolver } from '@guanghechen/path.types';
-export * from '@guanghechen/path.types';
+import { IPathResolver, IPathResolverParams, IWorkspacePathResolver } from '@guanghechen/types';
 
 /**
  * Locate a nearest filepath from the given `currentDir` which name included in the `filenames`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/path",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Path utils.",
   "author": {
     "name": "guanghechen",
@@ -8,17 +8,17 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/guanghechen/sora/tree/@guanghechen/path@1.0.3",
+    "url": "https://github.com/guanghechen/sora/tree/@guanghechen/path@2.0.0",
     "directory": "packages/path"
   },
-  "homepage": "https://github.com/guanghechen/sora/tree/@guanghechen/path@1.0.3/packages/path#readme",
+  "homepage": "https://github.com/guanghechen/sora/tree/@guanghechen/path@2.0.0/packages/path#readme",
   "type": "module",
   "exports": {
     ".": {
+      "types": "./lib/types/index.d.ts",
       "source": "./src/index.ts",
       "import": "./lib/esm/index.mjs",
-      "require": "./lib/cjs/index.cjs",
-      "types": "./lib/types/index.d.ts"
+      "require": "./lib/cjs/index.cjs"
     }
   },
   "source": "./src/index.ts",
@@ -26,13 +26,6 @@
   "module": "./lib/esm/index.mjs",
   "types": "./lib/types/index.d.ts",
   "license": "MIT",
-  "scripts": {
-    "build": "rollup -c ../../rollup.config.mjs",
-    "clean": "rimraf lib",
-    "test": "vitest run --config ../../vitest.config.ts",
-    "test:coverage": "vitest run --config ../../vitest.config.ts --coverage",
-    "test:update": "vitest run --config ../../vitest.config.ts -u"
-  },
   "files": [
     "lib/",
     "!lib/**/*.map",
@@ -42,7 +35,13 @@
     "README.md"
   ],
   "dependencies": {
-    "@guanghechen/path.types": "^2.0.0"
+    "@guanghechen/types": "^2.0.1"
   },
-  "gitHead": "12990a720b31d50d217e2e17a6191256dc94eda6"
-}
+  "scripts": {
+    "build": "rollup -c ../../rollup.config.mjs",
+    "clean": "rimraf lib",
+    "test": "vitest run --config ../../vitest.config.ts",
+    "test:coverage": "vitest run --config ../../vitest.config.ts --coverage",
+    "test:update": "vitest run --config ../../vitest.config.ts -u"
+  }
+}