fs: move fs/promises to fs.promises

[cjihrig]

Refs: nodejs/TSC#389

This only deals with moving fs/promises to fs.promises, and nothing about a CLI flag.

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[joyeecheung]

Is it going to be backported to v10? Per the stability index, this is possible, and it does not seem too late while v10.0.0 is just out.

https://nodejs.org/api/documentation.html#documentation_stability_index

Stability: 1 - Experimental This feature is still under active development and subject to non-backwards compatible changes, or even removal, in any future version. Use of the feature is not recommended in production environments. Experimental features are not subject to the Node.js Semantic Versioning model.

[joyeecheung]

cc @nodejs/tsc

[jasnell]

Yes, it would need to be.

[MylesBorins]

LGTM.

I would like to see this land before next Tuesday if possible so we can cut a 10.1.0 that includes this ASAP

[cjihrig]

All green CI: https://ci.nodejs.org/job/node-test-pull-request/14675/

[rauschma]

Wouldn’t this make this API less convenient to use with ES modules?

Compare:

import {mkdir} from 'fs/promises';

import * as fs from 'fs';
const {mkdir} = fs.promises;

[joyeecheung]

@rauschma This is not about this API, see the discussion in nodejs/TSC#389 . In summary:

1. We are figuring out a policy for adding new module ids, possibly under @nodejs or @core
2. We introduced the WHATWG URL as require('url').URL, for consistency the promise API should've been mounted the similar way (or the WHATWG URL should've been mounted as require('url/whatwg') but the ship may have been sailed). Anyway the module id is still subject to change while it is experimental and putting it under an existing module allows us to figure out the namespace issue while the users experiment with the functionality. The module id is not final at this point. The fact that it is experimental means it could change or even disappear (unlikely though) in the future.

[EvanCarroll]

Using 10.9, this isn't working for me at all,

This is all that's in my .js,

import fs from 'fs';

When I try to run node --experimental-modules --loader ./test.js

> (node:3278) ExperimentalWarning: The ESM module loader is experimental.
(node:3278) UnhandledPromiseRejectionWarning: /home/ecarroll/code/pg-url/sql/test.js:1
(function (exports, require, module, __filename, __dirname) { import fs from 'fs';
                                                                     ^^

SyntaxError: Unexpected identifier
    at new Script (vm.js:73:7)
    at createScript (vm.js:245:10)
    at Proxy.runInThisContext (vm.js:297:10)
    at Module._compile (internal/modules/cjs/loader.js:657:28)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)
    at Module.load (internal/modules/cjs/loader.js:599:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)
    at Function.Module._load (internal/modules/cjs/loader.js:530:3)
    at createDynamicModule (internal/modules/esm/translators.js:56:15)
    at setExecutor (internal/modules/esm/create_dynamic_module.js:50:23)
(node:3278) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:3278) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

[devsnek]

@EvanCarroll rename test.js to test.mjs

[KonradLinkowski]

Maybe you should change it in the documentation https://nodejs.org/api/fs.html#fs_promise_example

[devsnek]

@KonradLinkowski fs/promises was added back at a later date.

[KonradLinkowski]

@devsnek So something may be wrong with github actions, because I was getting Error: Cannot find module 'fs/promises' error until I used fs.promises.

[ljharb]

@KonradLinkowski it depends what node version you're using. node v10.0.0 or >= v14.0 are required for fs/promises to work.

[KonradLinkowski]

@ljharb Oh ok, I was pretty sure that node12 is the latest version, but as you can see I was very wrong xd
Thanks for help :)