@eliware/path

An ESM/Jest/Node-friendly path utility for resolving file and directory paths in ESM environments.

Table of Contents

• Features
• Installation
• Usage
  • ESM Example
    • Dynamic Import Example
• API
• TypeScript
• License

Features

• Unified API for ESM: pass either import.meta or a string (like __dirname)
• Works seamlessly in Node.js, Jest, and modern ESM environments
• TypeScript type definitions included
• Simple, dependency-free, and well-tested
• pathUrl, resolvePath, and relativePath helpers based on import.meta
• fileUrlToPath for converting file URLs back to filesystem paths

Requirements

• Node.js 26 or newer
• Native ESM support

Installation

npm install @eliware/path

Usage

ESM Example

import path, { fileUrlToPath, pathUrl, relativePath, resolvePath } from '@eliware/path';

// for ESM, we need to pass import.meta
const envFile = path(import.meta, ".env");
console.log(envFile);

// Get a file URL href for dynamic import
const envFileUrl = pathUrl(import.meta, ".env");
console.log(envFileUrl);
// import(envFileUrl).then(mod => ...);

Dynamic Import Example

// ESM
import { pathUrl } from '@eliware/path';
const mod = await import(pathUrl(import.meta, './my-module.mjs'));

API

getCurrentFilename(metaOrDir?: ImportMeta | string): string

Returns the absolute path to the current file or directory. Pass import.meta (ESM) or a string (e.g. __dirname). Throws if unavailable.

getCurrentDirname(metaOrDir?: ImportMeta | string, dirnameFn?: (path: string) => string): string

Returns the absolute path to the current directory. Pass import.meta (ESM) or a string (e.g. __dirname). Throws if unavailable.

default path(metaOrDir: ImportMeta | string, ...segments: string[]): string

Joins the current dirname (from import.meta or a string) with provided segments to form an absolute path.

pathUrl(metaOrDir: ImportMeta | string, ...segments: string[]): string

Returns a file URL href string for the resolved path, suitable for use with dynamic import() on all platforms.

Errors / Troubleshooting

Pass import.meta or a directory string to the helpers. Missing or invalid bases throw an error. Paths use the host platform’s native separators; pathUrl() returns a file URL suitable for dynamic imports.

Development

npm test
npm run test:gaps
npm run lint
npm run typecheck
npm run pack

Security

Path helpers do not sandbox or validate filesystem access. Treat user-controlled path segments as untrusted and apply application-specific traversal and permission checks before reading or writing files.

TypeScript

Type definitions are included:

export function getCurrentFilename(metaOrDir?: ImportMeta | string): string;
export function getCurrentDirname(metaOrDir?: ImportMeta | string, dirnameFn?: (path: string) => string): string;
export const path: (metaOrDir: ImportMeta | string, ...segments: string[]) => string;
export function pathUrl(metaOrDir: ImportMeta | string, ...segments: string[]): string;
export default path;

Support

For help, questions, or to chat with the author and community, visit:

eliware.org on Discord

License

MIT © 2025 Eli Sterling, eliware.org

Links

• Home Page
• GitHub
• npm
• Discord