@zokugun / fs-path

紧凑的路径实用程序集，补充了Node的内置功能 path 模块。

功能

• 波浪膨胀：膨胀 ~ 到当前用户的主目录 untildify.
• 安全连接和解析：在组合路径时避免常见陷阱的帮助程序。
• 有用的实用程序：检索父路径、绝对规范化和平台感知的帮助程序。
• 带有ESM和CJS构建的小包

安装

npm add @zokugun/fs-path

快速入门

import { isInDir, join, resolve } from '@zokugun/fs-path'

const configDir = resolve('~/.config/myapp')
const dataFile = join(configDir, 'data.json')

console.log('Config dir:', configDir)
console.log('Data file:', dataFile)

console.log('Is data file inside config dir?', isInDir(dataFile, configDir))

此示例展开当前用户的主目录，安全地连接路径，并输出解析后的绝对路径 configDir.

API参考

• absolute(...paths: string[]): string：返回标准化的绝对路径。
• isAbsolute(path: string): boolean:返回 true 当 path 是当前平台的绝对值。
• isInDir(path: string, parent: string): boolean:返回 true 当 path 等于还是包含在 parent.
• isInDirs(path: string, parents: string[]): boolean:返回 true 当 path 等于或包含在其中一个 parents.
• isSafePath(path: string, options?): boolean:返回 true 当 path 被认为是安全的使用(防止可疑的部分，如 .. 当适合平台时)。
• isSafeSegment(segment: string, target?: Target | 'auto'): boolean:返回 true 当单个路径段是安全的（不包含路径分隔符或遍历序列）。
• join(...paths: string[]): string：连接路径段。
• leafExt(path: string, length?: number): string：返回扩展名。
• leafName(path: string, extension?: number | string): string：返回的基名 path 带/不带扩展。
• matchesGlob?(path: string, pattern: string): boolean：可选的平台提供的全局匹配器（当可用时）。
• normalize(path: string): string：将路径归一化(与 path.normalize）。
• parentName(path: string): string的父名称 path.
• parentPath(path: string): string：返回的父目录 path.
• relative(from: string, to: string): string：计算相对路径 from 来 to.
• resolve(...paths: string[]): string：将路径段解析为绝对路径。支持波浪扩展：
  • ~ 展开到当前用户的主目录。
  • ~username/... 尝试在可用时扩展到该用户的主目录。
• sanitize(path: string, options?): Result<string>：返回的净化形式 path 不安全段归一化。
• untildify(path: string): string：扩大领先地位 ~ 或者 ~username 到主目录，或者返回 path 不变。
• delimiter：平台特定字符(;/:）。
• separator：平台特定字符(\//）。

export type PlatformPath = {
    readonly delimiter: ';' | ':';
    readonly separator: '\\' | '/';
    readonly posix: PlatformPath;
    readonly win32: PlatformPath;
    absolute: (...paths: string[]) => string;
    isAbsolute: (path: string) => boolean;
    isInDir(path: string, parent: string): boolean;
    isInDirs(path: string, parents: string[]): boolean;
    isSafePath: (path: string, options?: {
        parent?: string | null;
        parents?: string | string[] | null;
        target?: Target | 'auto';
    }) => boolean;
    isSafeSegment: (segment: string, target?: Target | 'auto') => boolean;
    join: (...paths: string[]) => string;
    leafExt: (path: string, length?: number) => string;
    leafName: (path: string, extension?: number | string) => string;
    matchesGlob?: (path: string, pattern: string) => boolean;
    normalize: (path: string) => string;
    parentName: (path: string) => string;
    parentPath: (path: string) => string;
    relative: (from: string, to: string) => string;
    resolve: (...paths: string[]) => string;
    sanitize(path: string, options?: {
        parent?: string | null;
        parents?: string | string[] | null;
        replacement?: string | null;
        target?: Target | 'auto'
    }) => Result<string>
    untildify: (path: string) => string;
};

与Node的比较 path

这个库有意地反映了Node的许多库 path api，但提供了微小的人体工程学差异和有用的额外功能：

• join(...paths):包装 path.join。返回 '' 而不是 . 当联接结果为当前目录时。
• isAbsolute(path)， normalize(path)， relative(from, to)：直接映射到 path.isAbsolute， path.normalize, path.relative 分别。
• parentPath(file):包装 path.dirname。返回 '' 而不是 . 为了与 join.
• resolve(...paths):包装 path.resolve 但增加了波浪膨胀(~ 和 ~username)，然后再解决。
• delimiter：与 path.delimiter 在当前的平台上。
• separator：与 path.sep 在当前的平台上。

贡献

欢迎投稿。请:

• 在存储库讨论下打开问题和特性请求。
• 遵循 CONTRIBUTING.md.

捐款

通过成为财务贡献者来支持这个项目。

	ko-fi.com/daiyam
	liberapay.com/daiyam/donate
	paypal.me / daiyam99

许可证

版权所有©2026-present Baptiste Augrain

根据 麻省理工学院的许可.