path.md

🛤️ Path Utilities

Simple helpers for consistent and cross-platform path manipulation.

---

Access the path utility

import atomix from '@nasriya/atomix';

const path = atomix.path;

---

The APIs

API	Description
normalizePath	Resolves and normalizes a path, lowercasing it on Windows.
sanitizeName	Sanitizes a filename or folder name by replacing/removing illegal characters.
isSubPath	Checks if one path is a sub-path of another.
getFileNameWithoutExtension	Gets the filename without its extension.
changeExtension	Changes the file extension of a given path.
isValidPath	Checks if a path string is valid.
relativeToCwd	Returns the relative path from the current working directory.
isLikelyPath	Heuristically determines if the given string is likely a file path.

---

API Details

🛤️ normalizePath

Signature: normalizePath(path: string): string

Resolves a given path to an absolute normalized path. On Windows, converts it to lowercase for consistency.

const normalized = path.normalizePath('./MyFolder/../file.txt');
console.log(normalized);
// Output (on Windows): 'c:\\users\\user\\file.txt'
// Output (on Linux/macOS): '/home/user/file.txt'

🧹 sanitizeName

Signature: sanitizeName(name: string, replacement?: string): string

Sanitizes a filename or folder name by replacing/removing illegal characters.

const safeName = path.sanitizeName('my*illegal:file?.txt');
console.log(safeName);
// Output: 'my_illegal_file_.txt'

📁 isSubPath

Signature: isSubPath(childPath: string, parentPath: string): boolean

Checks if one path is a sub-path of another.

const child = '/Users/alice/projects/myapp/src';
const parent = '/Users/alice/projects/myapp';

const result = path.isSubPath(child, parent);
console.log(result);  // true

📄 getFileNameWithoutExtension

Signature: getFileNameWithoutExtension(filePath: string): string

Gets the filename without its extension.

const filename = path.getFileNameWithoutExtension('/foo/bar/data.json');
console.log(filename);  // 'data'

🔄 changeExtension

Signature: changeExtension(filePath: string, newExt: string): string

Changes the file extension of a given path.

const newPath = path.changeExtension('/foo/bar/data.txt', '.json');
console.log(newPath);  // '/foo/bar/data.json'

✅ isValidPath

Signature: isValidPath(path_: string): boolean

Checks if a path string is valid.

console.log(path.isValidPath('valid-file.txt'));   // true
console.log(path.isValidPath('inva|id.txt'));      // false on Windows
console.log(path.isValidPath(''));                 // false

📂 relativeToCwd

Signature: relativeToCwd(path_: string): string

Returns the relative path from the current working directory.

const relativePath = path.relativeToCwd('/Users/alice/projects/myapp/data.json');
console.log(relativePath);
// 'projects/myapp/data.json' (depending on current working dir)

🤔 isLikelyPath

Signature: isLikelyPath(path_: string): boolean

Heuristically determines if the given string is likely a file path.

console.log(path.isLikelyPath('/Users/alice/projects/myapp/data.json'));  // true
console.log(path.isLikelyPath('inva|id.txt'));                            // false
console.log(path.isLikelyPath(''));                                       // false