Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fs: drop duplicate API in promises mode #20559

Merged
merged 1 commit into from
May 19, 2018
Merged

fs: drop duplicate API in promises mode #20559

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions benchmark/fs/bench-stat-promise.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,12 @@ const bench = common.createBenchmark(main, {
});

async function run(n, statType) {
const arg = statType === 'fstat' ?
await fsPromises.open(__filename, 'r') : __filename;
const handleMode = statType === 'fstat';
const arg = handleMode ? await fsPromises.open(__filename, 'r') : __filename;
let remaining = n;
bench.start();
while (remaining-- > 0)
await fsPromises[statType](arg);
await (handleMode ? arg.stat() : fsPromises[statType](arg));
bench.end(n);

if (typeof arg.close === 'function')
Expand Down
184 changes: 0 additions & 184 deletions doc/api/fs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3797,128 +3797,6 @@ fsPromises.copyFile('source.txt', 'destination.txt', COPYFILE_EXCL)
.catch(() => console.log('The file could not be copied'));
```

### fsPromises.fchmod(filehandle, mode)
<!-- YAML
added: v10.0.0
-->

* `filehandle` {FileHandle}
* `mode` {integer}
* Returns: {Promise}

Asynchronous fchmod(2). The `Promise` is resolved with no arguments upon
success.

### fsPromises.fchown(filehandle, uid, gid)
<!-- YAML
added: v10.0.0
-->

* `filehandle` {FileHandle}
* `uid` {integer}
* `gid` {integer}
* Returns: {Promise}

Changes the ownership of the file represented by `filehandle` then resolves
the `Promise` with no arguments upon success.

### fsPromises.fdatasync(filehandle)
<!-- YAML
added: v10.0.0
-->

* `filehandle` {FileHandle}
* Returns: {Promise}

Asynchronous fdatasync(2). The `Promise` is resolved with no arguments upon
success.

### fsPromises.fstat(filehandle)
<!-- YAML
added: v10.0.0
-->

* `filehandle` {FileHandle}
* Returns: {Promise}

Retrieves the [`fs.Stats`][] for the given `filehandle`.

### fsPromises.fsync(filehandle)
<!-- YAML
added: v10.0.0
-->

* `filehandle` {FileHandle}
* Returns: {Promise}

Asynchronous fsync(2). The `Promise` is resolved with no arguments upon
success.

### fsPromises.ftruncate(filehandle[, len])
<!-- YAML
added: v10.0.0
-->

* `filehandle` {FileHandle}
* `len` {integer} **Default:** `0`
* Returns: {Promise}

Truncates the file represented by `filehandle` then resolves the `Promise`
with no arguments upon success.

If the file referred to by the `FileHandle` was larger than `len` bytes, only
the first `len` bytes will be retained in the file.

For example, the following program retains only the first four bytes of the
file:

```js
console.log(fs.readFileSync('temp.txt', 'utf8'));
// Prints: Node.js

async function doTruncate() {
const fd = await fsPromises.open('temp.txt', 'r+');
await fsPromises.ftruncate(fd, 4);
console.log(fs.readFileSync('temp.txt', 'utf8')); // Prints: Node
}

doTruncate().catch(console.error);
```

If the file previously was shorter than `len` bytes, it is extended, and the
extended part is filled with null bytes (`'\0'`). For example,

```js
console.log(fs.readFileSync('temp.txt', 'utf8'));
// Prints: Node.js

async function doTruncate() {
const fd = await fsPromises.open('temp.txt', 'r+');
await fsPromises.ftruncate(fd, 10);
console.log(fs.readFileSync('temp.txt', 'utf8')); // Prints Node.js\0\0\0
}

doTruncate().catch(console.error);
```

The last three bytes are null bytes (`'\0'`), to compensate the over-truncation.

### fsPromises.futimes(filehandle, atime, mtime)
<!-- YAML
added: v10.0.0
-->

* `filehandle` {FileHandle}
* `atime` {number|string|Date}
* `mtime` {number|string|Date}
* Returns: {Promise}

Change the file system timestamps of the object referenced by the supplied
`FileHandle` then resolves the `Promise` with no arguments upon success.

This function does not work on AIX versions before 7.1, it will resolve the
`Promise` with an error using code `UV_ENOSYS`.

### fsPromises.lchmod(path, mode)
<!-- YAML
deprecated: v10.0.0
Expand Down Expand Up @@ -4027,35 +3905,6 @@ by [Naming Files, Paths, and Namespaces][]. Under NTFS, if the filename contains
a colon, Node.js will open a file system stream, as described by
[this MSDN page][MSDN-Using-Streams].

### fsPromises.read(filehandle, buffer, offset, length, position)
<!-- YAML
added: v10.0.0
-->

* `filehandle` {FileHandle}
* `buffer` {Buffer|Uint8Array}
* `offset` {integer}
* `length` {integer}
* `position` {integer}
* Returns: {Promise}

Read data from the file specified by `filehandle`.

`buffer` is the buffer that the data will be written to.

`offset` is the offset in the buffer to start writing at.

`length` is an integer specifying the number of bytes to read.

`position` is an argument specifying where to begin reading from in the file.
If `position` is `null`, data will be read from the current file position,
and the file position will be updated.
If `position` is an integer, the file position will remain unchanged.

Following successful read, the `Promise` is resolved with an object with a
`bytesRead` property specifying the number of bytes read, and a `buffer`
property that is a reference to the passed in `buffer` argument.

### fsPromises.readdir(path[, options])
<!-- YAML
added: v10.0.0
Expand Down Expand Up @@ -4240,39 +4089,6 @@ The `atime` and `mtime` arguments follow these rules:
- If the value can not be converted to a number, or is `NaN`, `Infinity` or
`-Infinity`, an `Error` will be thrown.

### fsPromises.write(filehandle, buffer[, offset[, length[, position]]])
<!-- YAML
added: v10.0.0
-->

* `filehandle` {FileHandle}
* `buffer` {Buffer|Uint8Array}
* `offset` {integer}
* `length` {integer}
* `position` {integer}
* Returns: {Promise}

Write `buffer` to the file specified by `filehandle`.

The `Promise` is resolved with an object containing a `bytesWritten` property
identifying the number of bytes written, and a `buffer` property containing
a reference to the `buffer` written.

`offset` determines the part of the buffer to be written, and `length` is
an integer specifying the number of bytes to write.

`position` refers to the offset from the beginning of the file where this data
should be written. If `typeof position !== 'number'`, the data will be written
at the current position. See pwrite(2).

It is unsafe to use `fsPromises.write()` multiple times on the same file
without waiting for the `Promise` to be resolved (or rejected). For this
scenario, `fs.createWriteStream` is strongly recommended.

On Linux, positional writes do not work when the file is opened in append mode.
The kernel ignores the position argument and always appends the data to
the end of the file.

### fsPromises.writeFile(file, data[, options])
<!-- YAML
added: v10.0.0
Expand Down
9 changes: 0 additions & 9 deletions lib/internal/fs/promises.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -466,31 +466,22 @@ module.exports = {
access,
copyFile,
open,
read,
write,
rename,
truncate,
ftruncate,
rmdir,
fdatasync,
fsync,
mkdir,
readdir,
readlink,
symlink,
fstat,
lstat,
stat,
link,
unlink,
fchmod,
chmod,
lchmod,
lchown,
fchown,
chown,
utimes,
futimes,
realpath,
mkdtemp,
writeFile,
Expand Down
23 changes: 5 additions & 18 deletions test/parallel/test-fs-promises.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,26 +11,18 @@ const {
access,
chmod,
copyFile,
fchmod,
fdatasync,
fstat,
fsync,
ftruncate,
futimes,
link,
lstat,
mkdir,
mkdtemp,
open,
read,
readdir,
readlink,
realpath,
rename,
rmdir,
stat,
symlink,
write,
unlink,
utimes
} = fsPromises;
Expand Down Expand Up @@ -74,13 +66,13 @@ function verifyStatObject(stat) {
const handle = await open(dest, 'r+');
assert.strictEqual(typeof handle, 'object');

let stats = await fstat(handle);
let stats = await handle.stat();
verifyStatObject(stats);
assert.strictEqual(stats.size, 35);

await ftruncate(handle, 1);
await handle.truncate(1);

stats = await fstat(handle);
stats = await handle.stat();
verifyStatObject(stats);
assert.strictEqual(stats.size, 1);

Expand All @@ -90,15 +82,13 @@ function verifyStatObject(stat) {
stats = await handle.stat();
verifyStatObject(stats);

await fdatasync(handle);
await handle.datasync();
await fsync(handle);
await handle.sync();

const buf = Buffer.from('hello fsPromises');
const bufLen = buf.length;
await write(handle, buf);
const ret = await read(handle, Buffer.alloc(bufLen), 0, bufLen, 0);
await handle.write(buf);
const ret = await handle.read(Buffer.alloc(bufLen), 0, bufLen, 0);
assert.strictEqual(ret.bytesRead, bufLen);
assert.deepStrictEqual(ret.buffer, buf);

Expand All @@ -110,18 +100,15 @@ function verifyStatObject(stat) {
assert.deepStrictEqual(ret2.buffer, buf2);

await chmod(dest, 0o666);
await fchmod(handle, 0o666);
await handle.chmod(0o666);

// Mode larger than 0o777 should be masked off.
await chmod(dest, (0o777 + 1));
await fchmod(handle, 0o777 + 1);
await handle.chmod(0o777 + 1);

await utimes(dest, new Date(), new Date());

try {
await futimes(handle, new Date(), new Date());
await handle.utimes(new Date(), new Date());
} catch (err) {
// Some systems do not have futimes. If there is an error,
Expand Down