@superhero/path-resolver

Path Resolver

A utility for callbacks to resolved file paths, directories, symbolic links, and Node.js modules, ensuring a consistent path resolution.

Features

• File Resolution: Resolves absolute and relative file paths.
• Directory Resolution: Handles absolute and relative directory paths.
• Symbolic Link Handling: Resolves symbolic links to their target paths.
• Module Resolution: Supports resolving Node.js core modules, installed modules, and scoped packages.
• Error Handling: Provides meaningful error messages for invalid paths, non-existent modules, and unsupported path types.

Installation

npm install @superhero/path-resolver

Usage

Importing the Module

import PathResolver from '@superhero/path-resolver'

Resolving Paths

Basic Example

const pathResolver = new PathResolver()

const resolveFile      = async (filePath) => `Resolved file: ${filePath}`
const resolveDirectory = async (dirPath)  => `Resolved directory: ${dirPath}`

const result = await pathResolver.resolve('./mock/file.js', resolveFile, resolveDirectory)
console.log(result) // Outputs: Resolved file: /absolute/path/to/mock/file.js

API

PathResolver Class

resolve(providedPath, resolveFile, resolveDirectory)

• Resolves a given path or module using the provided callbacks.

Parameters:

• providedPath (string): The path or module name to resolve.
• resolveFile (function): Callback for handling file paths. Called with the resolved file path.
• resolveDirectory (function): Callback for handling directory paths. Called with the resolved directory path.

Returns:

• A promise that resolves to the result of either resolveFile or resolveDirectory.

Throws:

• E_RESOLVE_PATH: If the path or module cannot be resolved.

Examples

Resolving File Paths

const result = await pathResolver.resolve('./file.json', resolveFile, resolveDirectory)
console.log(result) // Resolved file: /absolute/path/to/file.json

Resolving Directory Paths

const result = await pathResolver.resolve('./directory', resolveFile, resolveDirectory)
console.log(result) // Resolved directory: /absolute/path/to/directory

Handling Symbolic Links

const result = await pathResolver.resolve('./symlink', resolveFile, resolveDirectory)
console.log(result) // Resolved directory: /absolute/path/to/real-target

Resolving Node.js Core Modules

const result = await pathResolver.resolve('node:fs', resolveFile, resolveDirectory)
console.log(result) // Resolved file: /absolute/path/to/core/module/fs.js

Resolving Scoped Packages

const result = await pathResolver.resolve('@superhero/path-resolver', resolveFile, resolveDirectory)
console.log(result) // Resolved file: /absolute/path/to/node_modules/@superhero/path-resolver/index.js

Handling Invalid Paths

try
{
  await pathResolver.resolve('./non-existent-path', resolveFile, resolveDirectory)
} 
catch(error) 
{
  console.error(error.code) // E_RESOLVE_PATH
}

Tests

This module includes a test suite. To run the tests:

npm test

Test Coverage

▶ @superhero/path-resolver
  ✔ Resolves file paths correctly (4.152623ms)
  ✔ Resolves directory paths correctly (1.573636ms)
  ✔ Handles symbolic links correctly (1.284275ms)
  ✔ Throws error for invalid symbolic link (1.924598ms)
  ✔ Throws error for invalid path (2.207014ms)
  ✔ Resolves paths to Node.js core modules (0.488862ms)
  ✔ Resolves paths to "@superhero/path-resolver" module (1.268896ms)
  ✔ Throws error for non-existent module (0.805901ms)
  ✔ Can use relative paths relative to the main directory (1.407842ms)
  ✔ Can alter basePath to determine the root to a relative path (0.668805ms)
  ✔ Can use parent directory in a relative path (0.571907ms)
  ✔ Throws error if not using a string as provided path to resolve (0.266317ms)
✔ @superhero/path-resolver (30.570623ms)

tests 12
pass 12

-----------------------------------------------------------------
file            | line % | branch % | funcs % | uncovered lines
-----------------------------------------------------------------
index.js        |  91.74 |    89.29 |  100.00 | 52 55-59 116-119
index.test.js   | 100.00 |   100.00 |   96.97 | 
-----------------------------------------------------------------
all files       |  96.45 |    95.08 |   97.44 | 
-----------------------------------------------------------------

Error Codes

• E_RESOLVE_PATH:
  • Thrown when the provided path or module cannot be resolved.

License

This project is licensed under the MIT License.

Contributing

Feel free to submit issues or pull requests for improvements or additional features.