@zokugun/fs-path 0.2.1 → 0.3.0

package/README.md

@@ -1,11 +1,13 @@
 [@zokugun/fs-path](https://github.com/zokugun/node-fs-path)
 ===========================================================
 
-[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
-[![NPM Version](https://img.shields.io/npm/v/@zokugun/fs-path.svg?colorB=green)](https://www.npmjs.com/package/@zokugun/fs-path)
-[![Donation](https://img.shields.io/badge/donate-ko--fi-green)](https://ko-fi.com/daiyam)
-[![Donation](https://img.shields.io/badge/donate-liberapay-green)](https://liberapay.com/daiyam/donate)
-[![Donation](https://img.shields.io/badge/donate-paypal-green)](https://paypal.me/daiyam99)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+[![NPM Version](https://img.shields.io/npm/v/@zokugun/fs-path?color=brightgreen)](https://www.npmjs.com/package/@zokugun/fs-path)
+[![NodeJS Version](https://img.shields.io/badge/node.js-%3E%3D%2018.20-green)](#requirements)
+[![Modules](https://img.shields.io/badge/modules-ESM%20%7C%20CJS-green)](#requirements)
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-f87171?logo=kofi&logoColor=white)](https://ko-fi.com/daiyam)
+[![Liberapay](https://img.shields.io/badge/Liberapay-facc15?logo=liberapay&logoColor=black)](https://liberapay.com/daiyam/donate)
+[![PayPal](https://img.shields.io/badge/PayPal-5277C3?logo=paypal&logoColor=white)](https://paypal.me/daiyam99)
 
 > Compact set of path utilities that complement Node's builtin `path` module.
 
@@ -15,7 +17,7 @@ Features
 - Tilde expansion: expand `~` to the current user's home directory with `untildify`.
 - Safe joining and resolving: helpers that avoid common pitfalls when composing paths.
 - Useful utilities: retrieve parent paths, absolute normalization, and platform-aware helpers.
-- Small package with ESM and CJS builds
+- Extension helpers: add, ensure, get, remove, replace, or trim file extensions.
 
 Installation
 ------------
@@ -24,6 +26,12 @@ Installation
 npm add @zokugun/fs-path
 ```
 
+Requirements
+------------
+
+- **Node.js**: `v18.20` or higher
+- **Modules**: ECMAScript Modules (`ESM`) or CommonJS (`CJS`)
+
 Quick Start
 -----------
 
@@ -51,10 +59,17 @@ API reference
 - `isSafePath(path: string, options?): boolean`: Return `true` when `path` is considered safe for use (guards against suspicious segments such as `..` when appropriate for the platform).
 - `isSafeSegment(segment: string, target?: Target | 'auto'): boolean`: Return `true` when a single path segment is safe (doesn't contain path separators or traversal sequences).
 - `join(...paths: string[]): string`: Join path segments.
+- `ext`: File-extension helpers:
+    - `ext.add(path: string, ext: string): string`: Append an extension, adding a leading dot when needed.
+    - `ext.ensure(path: string, ext: string, options?: ExtOptions): string`: Append the extension unless the path already has a matching extension.
+    - `ext.get(path: string, depth?: number): string`: Get the extension; `depth` selects multiple suffixes (for example, `2` returns `.tar.gz`).
+    - `ext.remove(path: string, ext: string): string`: Remove the matching trailing extension.
+    - `ext.replace(path: string, ext: string, options?: ExtOptions): string`: Trim a matching extension, then append the given extension.
+    - `ext.trim(path: string, options?: ExtOptions): string`: Remove a matching extension from the path.
 - `leafExt(path: string, length?: number): string`: Return the extensions.
 - `leafName(path: string, extension?: number | string): string`: Return the basename of `path` with/without the extensions.
 - `matchesGlob?(path: string, pattern: string): boolean`: Optional platform-provided glob matcher when available.
-- `normalize(path: string): string`: Normalize the path (same as `path.normalize`).
+- `normalize(path: string): string`: Normalize a path using the current platform's path rules.
 - `parentName(path: string): string`: Return the parent name of `path`.
 - `parentPath(path: string): string`: Return the parent directory of `path`.
 - `relative(from: string, to: string): string`: Compute the relative path from `from` to `to`.
@@ -67,12 +82,26 @@ API reference
 - `separator`: Platform-specific character (`\`/`/`).
 
 ```ts
+export type ExtOptions = {
+    depth?: number;
+    ignore?: string[];
+    maxLength?: number;
+};
+
 export type PlatformPath = {
     readonly delimiter: ';' | ':';
     readonly separator: '\\' | '/';
     readonly posix: PlatformPath;
     readonly win32: PlatformPath;
     absolute: (...paths: string[]) => string;
+    ext: {
+        add(path: string, ext: string): string;
+        ensure(path: string, ext: string, options?: ExtOptions): string;
+        get(path: string, depth?: number): string;
+        remove(path: string, ext: string): string;
+        replace(path: string, ext: string, options?: ExtOptions): string;
+        trim(path: string, options?: ExtOptions): string;
+    };
     isAbsolute: (path: string) => boolean;
     isInDir(path: string, parent: string): boolean;
     isInDirs(path: string, parents: string[]): boolean;
@@ -107,7 +136,8 @@ Comparison with Node's `path`
 This library intentionally mirrors many of Node's `path` APIs but provides small ergonomic differences and extra features where useful:
 
 - `join(...paths)`: wraps `path.join`. Returns `''` instead of `.` when the joined result is the current directory.
-- `isAbsolute(path)`, `normalize(path)`, `relative(from, to)`: direct mappings to `path.isAbsolute`, `path.normalize`, and `path.relative` respectively.
+- `isAbsolute(path)` and `relative(from, to)`: direct mappings to `path.isAbsolute` and `path.relative`.
+- `normalize(path)`: uses the current platform's path rules; on POSIX, backslashes are also treated as separators.
 - `parentPath(file)`: wraps `path.dirname`. Returns `''` instead of `.` for consistency with `join`.
 - `resolve(...paths)`: wraps `path.resolve` but adds tilde expansion (`~` and `~username`) before resolving.
 - `delimiter`: same value as `path.delimiter` on the current platform.

package/lib/cjs/ext/add.cjs

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.add = add;
+function add(path, ext) {
+    const trim = ext.trim();
+    if (trim.length === 0) {
+        return path;
+    }
+    if (trim[0] !== '.') {
+        return path + '.' + trim;
+    }
+    else {
+        return path + ext;
+    }
+}

package/lib/cjs/ext/add.d.cts

@@ -0,0 +1 @@
+export declare function add(path: string, ext: string): string;

package/lib/cjs/ext/calculateDepth.cjs

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateDepth = calculateDepth;
+function calculateDepth(ext) {
+    let depth = 0;
+    for (let i = 0; i < ext.length; i++) {
+        if (ext[i] === '.') {
+            depth += 1;
+        }
+    }
+    return depth;
+}

package/lib/cjs/ext/calculateDepth.d.cts

@@ -0,0 +1 @@
+export declare function calculateDepth(ext: string): number;

package/lib/cjs/ext/ensure.cjs

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensure = ensure;
+const isMatching_js_1 = require("./isMatching.cjs");
+const normalizeIgnore_js_1 = require("./normalizeIgnore.cjs");
+function ensure(_nodePath, localPath) {
+    return (path, ext, options = {}) => {
+        ext = ext.trim();
+        if (ext.length === 0) {
+            return path;
+        }
+        if (ext[0] !== '.') {
+            ext = '.' + ext;
+        }
+        const { maxLength } = options;
+        const { ignore, depth } = (0, normalizeIgnore_js_1.normalizeIgnore)(options.ignore, options.depth);
+        const old = localPath.ext.get(path, depth);
+        if (old.length > 0 && (0, isMatching_js_1.isMatching)(old, ignore, maxLength)) {
+            return path;
+        }
+        return path + ext;
+    };
+}

package/lib/cjs/ext/ensure.d.cts

@@ -0,0 +1,3 @@
+import type path from 'node:path';
+import type { ExtOptions, PlatformPath } from '../types.cjs';
+export declare function ensure(_nodePath: path.PlatformPath, localPath: PlatformPath): (path: string, ext: string, options?: ExtOptions) => string;

package/lib/cjs/{leaf-ext.cjs → ext/get.cjs}

@@ -1,9 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.leafExt = leafExt;
+exports.get = get;
 const is_it_type_1 = require("@zokugun/is-it-type");
-// eslint-disable-next-line unicorn/prevent-abbreviations
-function leafExt(nodePath, _localPath) {
+function get(nodePath, _localPath) {
     return (path, length) => {
         if ((0, is_it_type_1.isUndefined)(length)) {
             return nodePath.extname(path);

package/lib/cjs/ext/get.d.cts

@@ -0,0 +1,3 @@
+import type path from 'node:path';
+import type { PlatformPath } from '../types.cjs';
+export declare function get(nodePath: path.PlatformPath, _localPath: PlatformPath): (path: string, length?: number) => string;

package/lib/cjs/ext/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildExt = buildExt;
+const add_js_1 = require("./add.cjs");
+const ensure_js_1 = require("./ensure.cjs");
+const get_js_1 = require("./get.cjs");
+const remove_js_1 = require("./remove.cjs");
+const replace_js_1 = require("./replace.cjs");
+const trim_js_1 = require("./trim.cjs");
+function buildExt(nodePath, localPath) {
+    return {
+        add: add_js_1.add,
+        ensure: (0, ensure_js_1.ensure)(nodePath, localPath),
+        get: (0, get_js_1.get)(nodePath, localPath),
+        remove: (0, remove_js_1.remove)(nodePath, localPath),
+        replace: (0, replace_js_1.replace)(nodePath, localPath),
+        trim: (0, trim_js_1.trim)(nodePath, localPath),
+    };
+}

package/lib/cjs/ext/index.d.cts

@@ -0,0 +1,3 @@
+import type path from 'node:path';
+import type { PlatformPath } from '../types.cjs';
+export declare function buildExt(nodePath: path.PlatformPath, localPath: PlatformPath): PlatformPath['ext'];

package/lib/cjs/ext/isMatching.cjs

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMatching = isMatching;
+function isMatching(ext, ignore, maxLength) {
+    if (maxLength && ext.length > maxLength) {
+        return false;
+    }
+    return !ignore.includes(ext);
+}

package/lib/cjs/ext/isMatching.d.cts

@@ -0,0 +1 @@
+export declare function isMatching(ext: string, ignore: string[], maxLength: number | undefined): boolean;

package/lib/cjs/ext/normalizeIgnore.cjs

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeIgnore = normalizeIgnore;
+const calculateDepth_js_1 = require("./calculateDepth.cjs");
+function normalizeIgnore(option, depth) {
+    if (!option) {
+        return { depth, ignore: [] };
+    }
+    const ignore = [];
+    depth ??= 1;
+    for (let ext of option) {
+        ext = ext.trim();
+        if (ext.length === 0) {
+            continue;
+        }
+        if (ext[0] !== '.') {
+            ignore.push('.' + ext);
+        }
+        ignore.push(ext);
+        depth = Math.max(depth, (0, calculateDepth_js_1.calculateDepth)(ext));
+    }
+    return { depth, ignore };
+}

package/lib/cjs/ext/normalizeIgnore.d.cts

@@ -0,0 +1,4 @@
+export declare function normalizeIgnore(option: string[] | undefined, depth: number | undefined): {
+    depth: number | undefined;
+    ignore: string[];
+};

package/lib/cjs/ext/remove.cjs

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.remove = remove;
+const calculateDepth_js_1 = require("./calculateDepth.cjs");
+function remove(_nodePath, localPath) {
+    return (path, ext) => {
+        ext = ext.trim();
+        if (ext.length === 0) {
+            return path;
+        }
+        if (ext[0] !== '.') {
+            ext = '.' + ext;
+        }
+        const depth = (0, calculateDepth_js_1.calculateDepth)(ext);
+        if (localPath.ext.get(path, depth) === ext) {
+            return path.slice(0, path.length - ext.length);
+        }
+        return path;
+    };
+}

package/lib/cjs/ext/remove.d.cts

@@ -0,0 +1,3 @@
+import type path from 'node:path';
+import type { PlatformPath } from '../types.cjs';
+export declare function remove(_nodePath: path.PlatformPath, localPath: PlatformPath): (path: string, ext: string) => string;

package/lib/cjs/ext/replace.cjs

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.replace = replace;
+function replace(_nodePath, localPath) {
+    return (path, ext, options = {}) => {
+        ext = ext.trim();
+        if (ext.length === 0) {
+            return path;
+        }
+        if (ext[0] !== '.') {
+            ext = '.' + ext;
+        }
+        const trimmed = localPath.ext.trim(path, options);
+        return trimmed + ext;
+    };
+}

package/lib/cjs/ext/replace.d.cts

@@ -0,0 +1,3 @@
+import type path from 'node:path';
+import type { ExtOptions, PlatformPath } from '../types.cjs';
+export declare function replace(_nodePath: path.PlatformPath, localPath: PlatformPath): (path: string, ext: string, options?: ExtOptions) => string;

package/lib/cjs/ext/trim.cjs

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trim = trim;
+const isMatching_js_1 = require("./isMatching.cjs");
+const normalizeIgnore_js_1 = require("./normalizeIgnore.cjs");
+function trim(_nodePath, localPath) {
+    return (path, options = {}) => {
+        const { maxLength } = options;
+        let { ignore, depth } = (0, normalizeIgnore_js_1.normalizeIgnore)(options.ignore, options.depth);
+        if (depth && maxLength) {
+            while (depth > 0) {
+                const ext = localPath.ext.get(path, depth);
+                if ((0, isMatching_js_1.isMatching)(ext, ignore, maxLength)) {
+                    return path.slice(0, path.length - ext.length);
+                }
+                depth -= 1;
+            }
+        }
+        else {
+            const ext = localPath.ext.get(path, depth);
+            if ((0, isMatching_js_1.isMatching)(ext, ignore, maxLength)) {
+                return path.slice(0, path.length - ext.length);
+            }
+        }
+        return path;
+    };
+}

package/lib/cjs/ext/trim.d.cts

@@ -0,0 +1,3 @@
+import type path from 'node:path';
+import type { ExtOptions, PlatformPath } from '../types.cjs';
+export declare function trim(_nodePath: path.PlatformPath, localPath: PlatformPath): (path: string, options?: ExtOptions) => string;

package/lib/cjs/index.cjs

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.win32 = exports.untildify = exports.separator = exports.sanitize = exports.resolve = exports.relative = exports.posix = exports.isSafeSegment = exports.isSafePath = exports.isInDirs = exports.isInDir = exports.parentPath = exports.parentName = exports.normalize = exports.matchesGlob = exports.leafName = exports.leafExt = exports.join = exports.isAbsolute = exports.delimiter = exports.absolute = void 0;
+exports.win32 = exports.untildify = exports.separator = exports.sanitize = exports.resolve = exports.relative = exports.posix = exports.isSafeSegment = exports.isSafePath = exports.isInDirs = exports.isInDir = exports.parentPath = exports.parentName = exports.normalize = exports.matchesGlob = exports.leafName = exports.leafExt = exports.join = exports.isAbsolute = exports.ext = exports.delimiter = exports.absolute = void 0;
 const platform_js_1 = require("./platform.cjs");
-const { absolute, delimiter, isAbsolute, join, leafExt, leafName, matchesGlob, normalize, parentName, parentPath, isInDir, isInDirs, isSafePath, isSafeSegment, posix, relative, resolve, sanitize, separator, untildify, win32, } = platform_js_1.DEFAULT_PLATFORM;
+const { absolute, ext, delimiter, isAbsolute, join, leafExt, leafName, matchesGlob, normalize, parentName, parentPath, isInDir, isInDirs, isSafePath, isSafeSegment, posix, relative, resolve, sanitize, separator, untildify, win32, } = platform_js_1.DEFAULT_PLATFORM;
 exports.absolute = absolute;
+exports.ext = ext;
 exports.delimiter = delimiter;
 exports.isAbsolute = isAbsolute;
 exports.join = join;
@@ -30,6 +31,7 @@ exports.default = {
     PlatformPath: undefined,
     absolute,
     delimiter,
+    ext,
     isAbsolute,
     join,
     leafExt,

package/lib/cjs/index.d.cts

@@ -1,5 +1,12 @@
 import { type PlatformPath } from './types.cjs';
-declare const absolute: (...paths: string[]) => string, delimiter: ";" | ":", isAbsolute: (path: string) => boolean, join: (...paths: string[]) => string, leafExt: (path: string, length?: number) => string, leafName: (path: string, extension?: number | string) => string, matchesGlob: ((path: string, pattern: string) => boolean) | undefined, normalize: (path: string) => string, parentName: (path: string) => string, parentPath: (path: string) => string, isInDir: (path: string, dir: string) => boolean, isInDirs: (path: string, directories: string[]) => boolean, isSafePath: (path: string, options?: {
+declare const absolute: (...paths: string[]) => string, ext: {
+    add: (path: string, ext: string) => string;
+    ensure: (path: string, ext: string, options?: ExtOptions) => string;
+    get: (path: string, depth?: number) => string;
+    remove: (path: string, ext: string) => string;
+    replace: (path: string, ext: string, options?: ExtOptions) => string;
+    trim: (path: string, options?: ExtOptions) => string;
+}, delimiter: ";" | ":", isAbsolute: (path: string) => boolean, join: (...paths: string[]) => string, leafExt: (path: string, length?: number) => string, leafName: (path: string, extension?: number | string) => string, matchesGlob: ((path: string, pattern: string) => boolean) | undefined, normalize: (path: string) => string, parentName: (path: string) => string, parentPath: (path: string) => string, isInDir: (path: string, dir: string) => boolean, isInDirs: (path: string, directories: string[]) => boolean, isSafePath: (path: string, options?: {
     parent?: string | null;
     parents?: string | string[] | null;
     target?: Target | "auto";
@@ -9,13 +16,22 @@ declare const absolute: (...paths: string[]) => string, delimiter: ";" | ":", is
     replacement?: string | null;
     target?: Target | "auto";
 }) => DResult<string>, separator: "\\" | "/", untildify: (path: string) => string, win32: PlatformPath;
-export { type PlatformPath, absolute, delimiter, isAbsolute, join, leafExt, leafName, matchesGlob, normalize, parentName, parentPath, isInDir, isInDirs, isSafePath, isSafeSegment, posix, relative, resolve, sanitize, separator, untildify, win32, };
+export { type PlatformPath, absolute, delimiter, ext, isAbsolute, join, leafExt, leafName, matchesGlob, normalize, parentName, parentPath, isInDir, isInDirs, isSafePath, isSafeSegment, posix, relative, resolve, sanitize, separator, untildify, win32, };
+import { type ExtOptions } from "./types.cjs";
 import { type Target } from "@zokugun/fs-path-sanitize";
 import { type DResult } from "@zokugun/xtry/result";
 declare const _default: {
     PlatformPath: PlatformPath;
     absolute: (...paths: string[]) => string;
     delimiter: ";" | ":";
+    ext: {
+        add: (path: string, ext: string) => string;
+        ensure: (path: string, ext: string, options?: ExtOptions) => string;
+        get: (path: string, depth?: number) => string;
+        remove: (path: string, ext: string) => string;
+        replace: (path: string, ext: string, options?: ExtOptions) => string;
+        trim: (path: string, options?: ExtOptions) => string;
+    };
     isAbsolute: (path: string) => boolean;
     join: (...paths: string[]) => string;
     leafExt: (path: string, length?: number) => string;

package/lib/cjs/join.d.cts

@@ -1,3 +1,3 @@
-import type opath from 'path';
+import type opath from 'node:path';
 import { type PlatformPath } from './types.cjs';
 export declare function join(nodePath: opath.PlatformPath, _localPath: PlatformPath): (...paths: string[]) => string;

package/lib/cjs/leaf-name.d.cts

@@ -1,3 +1,3 @@
 import type path from 'node:path';
-import { type PlatformPath } from './types.cjs';
+import type { PlatformPath } from './types.cjs';
 export declare function leafName(nodePath: path.PlatformPath, _localPath: PlatformPath): (path: string, extension?: number | string) => string;

package/lib/cjs/normalize.cjs

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalize = normalize;
+function normalize(nodePath, localPath) {
+    if (localPath.separator === '\\') {
+        return nodePath.win32.normalize;
+    }
+    return (path) => {
+        let normalized = nodePath.posix.normalize(path);
+        if (!normalized.includes('\\')) {
+            return normalized;
+        }
+        if (normalized === '\\') {
+            return '/';
+        }
+        if (normalized.length <= 1) {
+            return normalized;
+        }
+        let prefix = '';
+        if (normalized.length > 4 && normalized[0] === '\\' && normalized[1] === '\\' && normalized[3] === '\\') {
+            const ch = normalized[2];
+            if ((ch === '?' || ch === '.')) {
+                normalized = normalized.slice(2);
+                prefix = '//';
+            }
+        }
+        return prefix + normalized.split(/[/\\]+/).join('/');
+    };
+}

package/lib/cjs/normalize.d.cts

@@ -0,0 +1,3 @@
+import type opath from 'node:path';
+import { type PlatformPath } from './types.cjs';
+export declare function normalize(nodePath: opath.PlatformPath, localPath: PlatformPath): (path: string) => string;

package/lib/cjs/platform.cjs

@@ -6,38 +6,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_PLATFORM = void 0;
 const node_path_1 = __importDefault(require("node:path"));
 const absolute_js_1 = require("./absolute.cjs");
+const index_js_1 = require("./ext/index.cjs");
 const is_in_dir_js_1 = require("./is-in-dir.cjs");
-// eslint-disable-next-line unicorn/prevent-abbreviations
 const is_in_dirs_js_1 = require("./is-in-dirs.cjs");
 const is_safe_path_js_1 = require("./is-safe-path.cjs");
 const is_safe_segment_js_1 = require("./is-safe-segment.cjs");
 const join_js_1 = require("./join.cjs");
-// eslint-disable-next-line unicorn/prevent-abbreviations
-const leaf_ext_js_1 = require("./leaf-ext.cjs");
 const leaf_name_js_1 = require("./leaf-name.cjs");
+const normalize_js_1 = require("./normalize.cjs");
 const parent_name_js_1 = require("./parent-name.cjs");
 const parent_path_js_1 = require("./parent-path.cjs");
 const resolve_js_1 = require("./resolve.cjs");
 const sanitize_js_1 = require("./sanitize.cjs");
 const untildify_js_1 = require("./untildify.cjs");
 function buildPlatform(path) {
-    const { delimiter, isAbsolute, normalize, relative, sep: separator, } = path;
+    const { delimiter, isAbsolute, relative, sep: separator, } = path;
     const result = {
         delimiter,
         separator,
         isAbsolute,
         matchesGlob: path.matchesGlob ?? undefined,
-        normalize,
         relative,
     };
+    const ext = (0, index_js_1.buildExt)(path, result);
     result.absolute = (0, absolute_js_1.absolute)(path, result);
+    result.ext = ext;
     result.isInDir = (0, is_in_dir_js_1.isInDir)(path, result);
     result.isInDirs = (0, is_in_dirs_js_1.isInDirs)(path, result);
     result.isSafePath = (0, is_safe_path_js_1.isSafePath)(path, result);
     result.isSafeSegment = (0, is_safe_segment_js_1.isSafeSegment)(path, result);
     result.join = (0, join_js_1.join)(path, result);
-    result.leafExt = (0, leaf_ext_js_1.leafExt)(path, result);
+    result.leafExt = ext.get;
     result.leafName = (0, leaf_name_js_1.leafName)(path, result);
+    result.normalize = (0, normalize_js_1.normalize)(path, result);
     result.parentName = (0, parent_name_js_1.parentName)(path, result);
     result.parentPath = (0, parent_path_js_1.parentPath)(path, result);
     result.resolve = (0, resolve_js_1.resolve)(path, result);

package/lib/cjs/types.d.cts

@@ -1,11 +1,24 @@
 import { type Target } from '@zokugun/fs-path-sanitize';
 import { type DResult } from '@zokugun/xtry';
+export type ExtOptions = {
+    depth?: number;
+    ignore?: string[];
+    maxLength?: number;
+};
 export type PlatformPath = {
     readonly delimiter: ';' | ':';
     readonly separator: '\\' | '/';
     readonly posix: PlatformPath;
     readonly win32: PlatformPath;
     absolute: (...paths: string[]) => string;
+    ext: {
+        add: (path: string, ext: string) => string;
+        ensure: (path: string, ext: string, options?: ExtOptions) => string;
+        get: (path: string, depth?: number) => string;
+        remove: (path: string, ext: string) => string;
+        replace: (path: string, ext: string, options?: ExtOptions) => string;
+        trim: (path: string, options?: ExtOptions) => string;
+    };
     isAbsolute: (path: string) => boolean;
     isInDir: (path: string, dir: string) => boolean;
     isInDirs: (path: string, directories: string[]) => boolean;

package/lib/esm/ext/add.d.mts

@@ -0,0 +1 @@
+export declare function add(path: string, ext: string): string;

package/lib/esm/ext/add.mjs

@@ -0,0 +1,12 @@
+export function add(path, ext) {
+    const trim = ext.trim();
+    if (trim.length === 0) {
+        return path;
+    }
+    if (trim[0] !== '.') {
+        return path + '.' + trim;
+    }
+    else {
+        return path + ext;
+    }
+}

package/lib/esm/ext/calculateDepth.d.mts

@@ -0,0 +1 @@
+export declare function calculateDepth(ext: string): number;

package/lib/esm/ext/calculateDepth.mjs

@@ -0,0 +1,9 @@
+export function calculateDepth(ext) {
+    let depth = 0;
+    for (let i = 0; i < ext.length; i++) {
+        if (ext[i] === '.') {
+            depth += 1;
+        }
+    }
+    return depth;
+}

package/lib/esm/ext/ensure.d.mts

@@ -0,0 +1,3 @@
+import type path from 'node:path';
+import type { ExtOptions, PlatformPath } from '../types.mjs';
+export declare function ensure(_nodePath: path.PlatformPath, localPath: PlatformPath): (path: string, ext: string, options?: ExtOptions) => string;

package/lib/esm/ext/ensure.mjs

@@ -0,0 +1,20 @@
+import { isMatching } from './isMatching.mjs';
+import { normalizeIgnore } from './normalizeIgnore.mjs';
+export function ensure(_nodePath, localPath) {
+    return (path, ext, options = {}) => {
+        ext = ext.trim();
+        if (ext.length === 0) {
+            return path;
+        }
+        if (ext[0] !== '.') {
+            ext = '.' + ext;
+        }
+        const { maxLength } = options;
+        const { ignore, depth } = normalizeIgnore(options.ignore, options.depth);
+        const old = localPath.ext.get(path, depth);
+        if (old.length > 0 && isMatching(old, ignore, maxLength)) {
+            return path;
+        }
+        return path + ext;
+    };
+}

package/lib/esm/ext/get.d.mts

@@ -0,0 +1,3 @@
+import type path from 'node:path';
+import type { PlatformPath } from '../types.mjs';
+export declare function get(nodePath: path.PlatformPath, _localPath: PlatformPath): (path: string, length?: number) => string;

package/lib/esm/{leaf-ext.mjs → ext/get.mjs}

@@ -1,6 +1,5 @@
 import { isUndefined } from '@zokugun/is-it-type';
-// eslint-disable-next-line unicorn/prevent-abbreviations
-export function leafExt(nodePath, _localPath) {
+export function get(nodePath, _localPath) {
     return (path, length) => {
         if (isUndefined(length)) {
             return nodePath.extname(path);

package/lib/esm/ext/index.d.mts

@@ -0,0 +1,3 @@
+import type path from 'node:path';
+import type { PlatformPath } from '../types.mjs';
+export declare function buildExt(nodePath: path.PlatformPath, localPath: PlatformPath): PlatformPath['ext'];

package/lib/esm/ext/index.mjs

@@ -0,0 +1,16 @@
+import { add } from './add.mjs';
+import { ensure } from './ensure.mjs';
+import { get } from './get.mjs';
+import { remove } from './remove.mjs';
+import { replace } from './replace.mjs';
+import { trim } from './trim.mjs';
+export function buildExt(nodePath, localPath) {
+    return {
+        add,
+        ensure: ensure(nodePath, localPath),
+        get: get(nodePath, localPath),
+        remove: remove(nodePath, localPath),
+        replace: replace(nodePath, localPath),
+        trim: trim(nodePath, localPath),
+    };
+}

package/lib/esm/ext/isMatching.d.mts

@@ -0,0 +1 @@
+export declare function isMatching(ext: string, ignore: string[], maxLength: number | undefined): boolean;

package/lib/esm/ext/isMatching.mjs

@@ -0,0 +1,6 @@
+export function isMatching(ext, ignore, maxLength) {
+    if (maxLength && ext.length > maxLength) {
+        return false;
+    }
+    return !ignore.includes(ext);
+}

package/lib/esm/ext/normalizeIgnore.d.mts

@@ -0,0 +1,4 @@
+export declare function normalizeIgnore(option: string[] | undefined, depth: number | undefined): {
+    depth: number | undefined;
+    ignore: string[];
+};

package/lib/esm/ext/normalizeIgnore.mjs

@@ -0,0 +1,20 @@
+import { calculateDepth } from './calculateDepth.mjs';
+export function normalizeIgnore(option, depth) {
+    if (!option) {
+        return { depth, ignore: [] };
+    }
+    const ignore = [];
+    depth ??= 1;
+    for (let ext of option) {
+        ext = ext.trim();
+        if (ext.length === 0) {
+            continue;
+        }
+        if (ext[0] !== '.') {
+            ignore.push('.' + ext);
+        }
+        ignore.push(ext);
+        depth = Math.max(depth, calculateDepth(ext));
+    }
+    return { depth, ignore };
+}

package/lib/esm/ext/remove.d.mts

@@ -0,0 +1,3 @@
+import type path from 'node:path';
+import type { PlatformPath } from '../types.mjs';
+export declare function remove(_nodePath: path.PlatformPath, localPath: PlatformPath): (path: string, ext: string) => string;

package/lib/esm/ext/remove.mjs

@@ -0,0 +1,17 @@
+import { calculateDepth } from './calculateDepth.mjs';
+export function remove(_nodePath, localPath) {
+    return (path, ext) => {
+        ext = ext.trim();
+        if (ext.length === 0) {
+            return path;
+        }
+        if (ext[0] !== '.') {
+            ext = '.' + ext;
+        }
+        const depth = calculateDepth(ext);
+        if (localPath.ext.get(path, depth) === ext) {
+            return path.slice(0, path.length - ext.length);
+        }
+        return path;
+    };
+}

package/lib/esm/ext/replace.d.mts

@@ -0,0 +1,3 @@
+import type path from 'node:path';
+import type { ExtOptions, PlatformPath } from '../types.mjs';
+export declare function replace(_nodePath: path.PlatformPath, localPath: PlatformPath): (path: string, ext: string, options?: ExtOptions) => string;

package/lib/esm/ext/replace.mjs

@@ -0,0 +1,13 @@
+export function replace(_nodePath, localPath) {
+    return (path, ext, options = {}) => {
+        ext = ext.trim();
+        if (ext.length === 0) {
+            return path;
+        }
+        if (ext[0] !== '.') {
+            ext = '.' + ext;
+        }
+        const trimmed = localPath.ext.trim(path, options);
+        return trimmed + ext;
+    };
+}

package/lib/esm/ext/trim.d.mts

@@ -0,0 +1,3 @@
+import type path from 'node:path';
+import type { ExtOptions, PlatformPath } from '../types.mjs';
+export declare function trim(_nodePath: path.PlatformPath, localPath: PlatformPath): (path: string, options?: ExtOptions) => string;

package/lib/esm/ext/trim.mjs

@@ -0,0 +1,24 @@
+import { isMatching } from './isMatching.mjs';
+import { normalizeIgnore } from './normalizeIgnore.mjs';
+export function trim(_nodePath, localPath) {
+    return (path, options = {}) => {
+        const { maxLength } = options;
+        let { ignore, depth } = normalizeIgnore(options.ignore, options.depth);
+        if (depth && maxLength) {
+            while (depth > 0) {
+                const ext = localPath.ext.get(path, depth);
+                if (isMatching(ext, ignore, maxLength)) {
+                    return path.slice(0, path.length - ext.length);
+                }
+                depth -= 1;
+            }
+        }
+        else {
+            const ext = localPath.ext.get(path, depth);
+            if (isMatching(ext, ignore, maxLength)) {
+                return path.slice(0, path.length - ext.length);
+            }
+        }
+        return path;
+    };
+}

package/lib/esm/index.d.mts

@@ -1,5 +1,12 @@
 import { type PlatformPath } from './types.mjs';
-declare const absolute: (...paths: string[]) => string, delimiter: ";" | ":", isAbsolute: (path: string) => boolean, join: (...paths: string[]) => string, leafExt: (path: string, length?: number) => string, leafName: (path: string, extension?: number | string) => string, matchesGlob: ((path: string, pattern: string) => boolean) | undefined, normalize: (path: string) => string, parentName: (path: string) => string, parentPath: (path: string) => string, isInDir: (path: string, dir: string) => boolean, isInDirs: (path: string, directories: string[]) => boolean, isSafePath: (path: string, options?: {
+declare const absolute: (...paths: string[]) => string, ext: {
+    add: (path: string, ext: string) => string;
+    ensure: (path: string, ext: string, options?: ExtOptions) => string;
+    get: (path: string, depth?: number) => string;
+    remove: (path: string, ext: string) => string;
+    replace: (path: string, ext: string, options?: ExtOptions) => string;
+    trim: (path: string, options?: ExtOptions) => string;
+}, delimiter: ";" | ":", isAbsolute: (path: string) => boolean, join: (...paths: string[]) => string, leafExt: (path: string, length?: number) => string, leafName: (path: string, extension?: number | string) => string, matchesGlob: ((path: string, pattern: string) => boolean) | undefined, normalize: (path: string) => string, parentName: (path: string) => string, parentPath: (path: string) => string, isInDir: (path: string, dir: string) => boolean, isInDirs: (path: string, directories: string[]) => boolean, isSafePath: (path: string, options?: {
     parent?: string | null;
     parents?: string | string[] | null;
     target?: Target | "auto";
@@ -9,13 +16,22 @@ declare const absolute: (...paths: string[]) => string, delimiter: ";" | ":", is
     replacement?: string | null;
     target?: Target | "auto";
 }) => DResult<string>, separator: "\\" | "/", untildify: (path: string) => string, win32: PlatformPath;
-export { type PlatformPath, absolute, delimiter, isAbsolute, join, leafExt, leafName, matchesGlob, normalize, parentName, parentPath, isInDir, isInDirs, isSafePath, isSafeSegment, posix, relative, resolve, sanitize, separator, untildify, win32, };
+export { type PlatformPath, absolute, delimiter, ext, isAbsolute, join, leafExt, leafName, matchesGlob, normalize, parentName, parentPath, isInDir, isInDirs, isSafePath, isSafeSegment, posix, relative, resolve, sanitize, separator, untildify, win32, };
+import { type ExtOptions } from "./types.mjs";
 import { type Target } from "@zokugun/fs-path-sanitize";
 import { type DResult } from "@zokugun/xtry";
 declare const _default: {
     PlatformPath: PlatformPath;
     absolute: (...paths: string[]) => string;
     delimiter: ";" | ":";
+    ext: {
+        add: (path: string, ext: string) => string;
+        ensure: (path: string, ext: string, options?: ExtOptions) => string;
+        get: (path: string, depth?: number) => string;
+        remove: (path: string, ext: string) => string;
+        replace: (path: string, ext: string, options?: ExtOptions) => string;
+        trim: (path: string, options?: ExtOptions) => string;
+    };
     isAbsolute: (path: string) => boolean;
     join: (...paths: string[]) => string;
     leafExt: (path: string, length?: number) => string;

package/lib/esm/index.mjs

@@ -1,13 +1,14 @@
 import { DEFAULT_PLATFORM } from './platform.mjs';
-const { absolute, delimiter, isAbsolute, join, leafExt, leafName, matchesGlob, normalize, parentName, parentPath, isInDir, isInDirs, isSafePath, isSafeSegment, posix, relative, resolve, sanitize, separator, untildify, win32, } = DEFAULT_PLATFORM;
+const { absolute, ext, delimiter, isAbsolute, join, leafExt, leafName, matchesGlob, normalize, parentName, parentPath, isInDir, isInDirs, isSafePath, isSafeSegment, posix, relative, resolve, sanitize, separator, untildify, win32, } = DEFAULT_PLATFORM;
 /* eslint-disable unicorn/prefer-export-from */
-export { absolute, delimiter, isAbsolute, join, leafExt, leafName, matchesGlob, normalize, parentName, parentPath, isInDir, isInDirs, isSafePath, isSafeSegment, posix, relative, resolve, sanitize, separator, untildify, win32, };
+export { absolute, delimiter, ext, isAbsolute, join, leafExt, leafName, matchesGlob, normalize, parentName, parentPath, isInDir, isInDirs, isSafePath, isSafeSegment, posix, relative, resolve, sanitize, separator, untildify, win32, };
 /* eslint-enable unicorn/prefer-export-from */
 // eslint-disable-next-line import/no-anonymous-default-export
 export default {
     PlatformPath: undefined,
     absolute,
     delimiter,
+    ext,
     isAbsolute,
     join,
     leafExt,

package/lib/esm/join.d.mts

@@ -1,3 +1,3 @@
-import type opath from 'path';
+import type opath from 'node:path';
 import { type PlatformPath } from './types.mjs';
 export declare function join(nodePath: opath.PlatformPath, _localPath: PlatformPath): (...paths: string[]) => string;

package/lib/esm/leaf-name.d.mts

@@ -1,3 +1,3 @@
 import type path from 'node:path';
-import { type PlatformPath } from './types.mjs';
+import type { PlatformPath } from './types.mjs';
 export declare function leafName(nodePath: path.PlatformPath, _localPath: PlatformPath): (path: string, extension?: number | string) => string;

package/lib/esm/normalize.d.mts

@@ -0,0 +1,3 @@
+import type opath from 'node:path';
+import { type PlatformPath } from './types.mjs';
+export declare function normalize(nodePath: opath.PlatformPath, localPath: PlatformPath): (path: string) => string;

package/lib/esm/normalize.mjs

@@ -0,0 +1,26 @@
+export function normalize(nodePath, localPath) {
+    if (localPath.separator === '\\') {
+        return nodePath.win32.normalize;
+    }
+    return (path) => {
+        let normalized = nodePath.posix.normalize(path);
+        if (!normalized.includes('\\')) {
+            return normalized;
+        }
+        if (normalized === '\\') {
+            return '/';
+        }
+        if (normalized.length <= 1) {
+            return normalized;
+        }
+        let prefix = '';
+        if (normalized.length > 4 && normalized[0] === '\\' && normalized[1] === '\\' && normalized[3] === '\\') {
+            const ch = normalized[2];
+            if ((ch === '?' || ch === '.')) {
+                normalized = normalized.slice(2);
+                prefix = '//';
+            }
+        }
+        return prefix + normalized.split(/[/\\]+/).join('/');
+    };
+}

package/lib/esm/platform.mjs

@@ -1,37 +1,38 @@
 import opath from 'node:path';
 import { absolute } from './absolute.mjs';
+import { buildExt } from './ext/index.mjs';
 import { isInDir } from './is-in-dir.mjs';
-// eslint-disable-next-line unicorn/prevent-abbreviations
 import { isInDirs } from './is-in-dirs.mjs';
 import { isSafePath } from './is-safe-path.mjs';
 import { isSafeSegment } from './is-safe-segment.mjs';
 import { join } from './join.mjs';
-// eslint-disable-next-line unicorn/prevent-abbreviations
-import { leafExt } from './leaf-ext.mjs';
 import { leafName } from './leaf-name.mjs';
+import { normalize } from './normalize.mjs';
 import { parentName } from './parent-name.mjs';
 import { parentPath } from './parent-path.mjs';
 import { resolve } from './resolve.mjs';
 import { sanitize } from './sanitize.mjs';
 import { untildify } from './untildify.mjs';
 function buildPlatform(path) {
-    const { delimiter, isAbsolute, normalize, relative, sep: separator, } = path;
+    const { delimiter, isAbsolute, relative, sep: separator, } = path;
     const result = {
         delimiter,
         separator,
         isAbsolute,
         matchesGlob: path.matchesGlob ?? undefined,
-        normalize,
         relative,
     };
+    const ext = buildExt(path, result);
     result.absolute = absolute(path, result);
+    result.ext = ext;
     result.isInDir = isInDir(path, result);
     result.isInDirs = isInDirs(path, result);
     result.isSafePath = isSafePath(path, result);
     result.isSafeSegment = isSafeSegment(path, result);
     result.join = join(path, result);
-    result.leafExt = leafExt(path, result);
+    result.leafExt = ext.get;
     result.leafName = leafName(path, result);
+    result.normalize = normalize(path, result);
     result.parentName = parentName(path, result);
     result.parentPath = parentPath(path, result);
     result.resolve = resolve(path, result);

package/lib/esm/types.d.mts

@@ -1,11 +1,24 @@
 import { type Target } from '@zokugun/fs-path-sanitize';
 import { type DResult } from '@zokugun/xtry';
+export type ExtOptions = {
+    depth?: number;
+    ignore?: string[];
+    maxLength?: number;
+};
 export type PlatformPath = {
     readonly delimiter: ';' | ':';
     readonly separator: '\\' | '/';
     readonly posix: PlatformPath;
     readonly win32: PlatformPath;
     absolute: (...paths: string[]) => string;
+    ext: {
+        add: (path: string, ext: string) => string;
+        ensure: (path: string, ext: string, options?: ExtOptions) => string;
+        get: (path: string, depth?: number) => string;
+        remove: (path: string, ext: string) => string;
+        replace: (path: string, ext: string, options?: ExtOptions) => string;
+        trim: (path: string, options?: ExtOptions) => string;
+    };
     isAbsolute: (path: string) => boolean;
     isInDir: (path: string, dir: string) => boolean;
     isInDirs: (path: string, directories: string[]) => boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@zokugun/fs-path",
 	"description": "Path utilities complementing the builtin path module",
-	"version": "0.2.1",
+	"version": "0.3.0",
 	"author": {
 		"name": "Baptiste Augrain",
 		"email": "daiyam@zokugun.org"
@@ -47,9 +47,9 @@
 		"watch:test": "tsc-watch -p test"
 	},
 	"dependencies": {
-		"@zokugun/fs-path-sanitize": "0.1.0",
+		"@zokugun/fs-path-sanitize": "0.2.2",
 		"@zokugun/is-it-type": "0.8.1",
-		"@zokugun/xtry": "0.11.6"
+		"@zokugun/xtry": "0.12.2"
 	},
 	"devDependencies": {
 		"@commitlint/cli": "20.5.3",
@@ -66,14 +66,14 @@
 		"@zokugun/eslint-config-style": "0.3.1",
 		"@zokugun/eslint-config-test": "0.2.0",
 		"@zokugun/eslint-config-ts": "0.3.2",
-		"@zokugun/fs-extra-plus": "0.6.2",
-		"@zokugun/tsc-leda": "0.9.1",
-		"eslint": "10.14.0",
+		"@zokugun/fs-extra-plus": "0.6.5",
+		"@zokugun/tsc-leda": "0.9.2",
+		"eslint": "10.13.0",
 		"fixpack": "4.0.0",
 		"husky": "9.1.7",
 		"lint-staged": "16.4.0",
 		"release-it": "20.2.1",
-		"rimraf": "6.1.3",
+		"rimraf": "6.1.4",
 		"taze": "19.17.2",
 		"tsc-watch": "7.2.1",
 		"typescript": "5.9.3",
@@ -107,9 +107,6 @@
 		"micromark-extension-math": {
 			"katex": "0.18.2"
 		},
-		"rimraf": {
-			"glob": "14.0.2"
-		},
 		"release-it": {
 			"undici": "7.30.1"
 		}

package/lib/cjs/leaf-ext.d.cts

@@ -1,3 +0,0 @@
-import type path from 'node:path';
-import { type PlatformPath } from './types.cjs';
-export declare function leafExt(nodePath: path.PlatformPath, _localPath: PlatformPath): (path: string, length?: number) => string;

package/lib/esm/leaf-ext.d.mts

@@ -1,3 +0,0 @@
-import type path from 'node:path';
-import { type PlatformPath } from './types.mjs';
-export declare function leafExt(nodePath: path.PlatformPath, _localPath: PlatformPath): (path: string, length?: number) => string;