esm: add import.meta.dirname and import.meta.filename

[jsumners]

This PR adds import.meta.dirname and import.meta.filename for ECMAScript Modules that are loaded from the local filesystem. In my view, these properties don’t make any sense for modules loaded from the network, but they are very desired for local modules. At least one recent issue (#47756) wanted them, and there exists at least two ecosystem modules to solve for them:

• https://www.npmjs.com/package/umeta
• https://www.npmjs.com/package/desm

The Problem

As it stands, to determine the containing directory of a script we must write code like:

import url from 'url'
import path from 'path'
const dirname = path.dirname(url.fileURLToPath(import.meta.url))

Of course, this needs to be repeated in every script that needs the information. With this PR, the code is reduced to:

const dirname = import.meta.__dirname

The developer doesn’t need to remember how to convert the file URL to a path and then resolve the directory from that.

External Discussion

The impetus for this PR is a recent Twitter discussion – https://twitter.com/jasnell/status/1677335322978295809

Notable change

In file:-based ES modules, new properties import.meta.filename and import.meta.dirname provide equivalents to CommonJS __filename and __dirname. In particular, import.meta.filename provides the full absolute path (as a file path, not URL) to the module; and import.meta.dirname provides the full absolute path to the module’s containing folder. These properties are missing for non-file:-based ES modules, such as those loaded from data: or https: URLs.

[mcollina]

lgtm

[github-actions]

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @mcollina.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment.

[mscdex]

This was suggested before in #39147. Has anything changed since then?

[mcollina]

This was suggested before in #39147. Has anything changed since then?

I think it is less controversial now. Everybody migrating to ESM needs to figure this out and it requires way too many steps to get those values.

[jcbhmr]

This may be of no concern, but Bun appears to use import.meta.dir and import.meta.path for these values: https://bun.sh/docs/api/import-meta idk if that's relevant tho. 🤷‍♂️

[aduh95]

I don't think it's a good idea to introduce this, we should move away from paths IMO.

[aduh95]

Everybody migrating to ESM needs to figure this out and it requires way too many steps to get those values.

Why do you need paths though? It shouldn't be necessary, URL should get you covered.

[mcollina]

Why do you need paths though? It shouldn't be necessary, URL should get you covered.

Most APIs from fs and path do not work well with URLs. Reading files relative to the current one is something everybody does all the time for all sorts of purposes. Currently, it takes quite a few lines of code to get the path for a file in the same directory:

import { fileURLToPath } from 'url'
import { dirname, join } from 'path'

const __dirname = dirname(url.fileURLToPath(import.meta.url))
const toAccess = join(__dirname, 'another_file')

[aduh95]

Most APIs from fs

That's wrong I think, all node:fs APIs works with either. If you see issues with node:fs and URL, please open an issue, that'd be a bug.

and path

That's kinda obvious, node:path is for paths, not URLs.

Reading files relative to the current one is something everybody does all the time for all sorts of purposes.

That's my point, you should be using URL for that. The equivalent to your code snippet would be:

const toAccess = new URL('./another_file', import.meta.url);

[aduh95]

Adding an explicit -1 on this because it already has an approval and I don't want it to land without some extensive discussion first.

I think this goes in the wrong direction. I'm happy to be proven wrong, but I guess there's also an ideological problem: I think using paths in ESM is a faux-pas, if one goes ESM, they should let paths be a relic of the past, and embrace URLs. I can see it can certainly be useful to have the proposed properties to convert a CJS module to ESM, but someone writing ESM from scratch should never need it, and it would be confusing to add something that works only on file: protocol, when I would prefer to see Node.js go in the direction of being more protocol agnostic.

[MoLow]

I think this goes in the wrong direction. I'm happy to be proven wrong, but I guess there's also an ideological problem: I think using paths in ESM is a faux-pas, if one goes ESM, they should let paths be a relic of the past, and embrace URLs. I can see it can certainly be useful to have the proposed properties to convert a CJS module to ESM, but someone writing ESM from scratch should never need it, and it would be confusing to add something that works only on file: protocol, when I would prefer to see Node.js go in the direction of being more protocol agnostic.

We should also consider if it will help the adoption of ESM and make migration easier / less painful.
even if there is an ideological issue - it is not very pragmatic to only provide a solution for "someone writing ESM from scratch".
even if one can argue it will never be needed, avoiding such utilities/helpers because they seem redundant can have a negative effect on the ecosystem.

[gengjiawen]

Almost shed tears, thank you

[gengjiawen]

if one goes ESM, they should let paths be a relic of the past, and embrace URLs.

It's like a muscle memory even can trace from python. It can avoid many mental burden from using esm, this is my mosted missed feature in esm.

Also many people trapped on this. lots of libs goto full esm have this info everywhere.

It's a good move in the long run, and way friendly for users back then when only cjs exists.

[gengjiawen]

I will share some my work experience, we used js almost everywhere, some are cjs, some are esm. When it comes to script job in CI and linux server, it's always have been cjs module. because __dirname and __filename used everywhere just like python. Esm equivalence is way verbose and less instinctive.

[mcollina]

@aduh95 The vast majority of the modules on npm only accept paths, not URLs. Therefore it adds quite a bit of a mental burden to do that. The recommendation you have is for all modules on NPM to start accepting file:// URLs as well as paths, or even only URLs. I don't think that's feasible.

Even modules that went all-in on ESM only use paths everywhere and not URLs, as an example take a look at https://vitest.dev/guide/#workspaces-support.

Overall I think adding __filename and __dirname will help the adoption of ESM.

[GeoffreyBooth]

FYI, Bun has also added import.meta.dirname and import.meta.filename: oven-sh/bun#8127