From 67c9a8e176571c08cb06fe924910deafd6dd87c6 Mon Sep 17 00:00:00 2001 From: Benjamin Gruenbaum Date: Tue, 2 Feb 2021 11:06:50 +0200 Subject: [PATCH] doc: improve promise terminology PR-URL: https://github.com/nodejs/node/pull/37181 Reviewed-By: Antoine du Hamel Reviewed-By: Zijian Liu Reviewed-By: Darshan Sen --- doc/api/fs.md | 109 +++++++++++++++++++++++++------------------------- 1 file changed, 55 insertions(+), 54 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 2f9dea37f3fd7f..04735faff41bee 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -56,7 +56,7 @@ fs.unlink('/tmp/hello', (err) => { ## Promise example -Promise-based operations return a `Promise` that is resolved when the +Promise-based operations return a `Promise` that is fulfilled when the asynchronous operation is complete. ```js @@ -335,7 +335,7 @@ added: v12.12.0 Asynchronously close the directory's underlying resource handle. Subsequent reads will result in errors. -A `Promise` is returned that will be resolved after the resource has been +A `Promise` is returned that will be fulfilled after the resource has been closed. ### `dir.close(callback)` @@ -379,8 +379,9 @@ added: v12.12.0 Asynchronously read the next directory entry via readdir(3) as an [`fs.Dirent`][]. -After the read is completed, a `Promise` is returned that will be resolved with -an [`fs.Dirent`][], or `null` if there are no more directory entries to read. +After the read is completed, a `Promise` is returned that will be fulfilled +with an [`fs.Dirent`][], or `null` if there are no more directory entries to +read. Directory entries returned by this function are in no particular order as provided by the operating system's underlying directory mechanisms. @@ -4740,8 +4741,8 @@ Instances of the `FileHandle` object are created internally by the Unlike the callback-based API (`fs.fstat()`, `fs.fchown()`, `fs.fchmod()`, and so on), a numeric file descriptor is not used by the promise-based API. Instead, the promise-based API uses the `FileHandle` class in order to help avoid -accidental leaking of unclosed file descriptors after a `Promise` is resolved or -rejected. +accidental leaking of unclosed file descriptors after a `Promise` is fulfilled +or rejected. #### Event: `'close'` -* Returns: {Promise} A `Promise` that will be resolved once the underlying +* Returns: {Promise} A `Promise` that will be fulfilled once the underlying file descriptor is closed, or will be rejected if an error occurs while closing. @@ -4822,7 +4823,7 @@ added: v10.0.0 * Returns: {Promise} -Asynchronous fdatasync(2). The `Promise` is resolved with no arguments upon +Asynchronous fdatasync(2). The `Promise` is fulfilled with no arguments upon success. #### `filehandle.fd` @@ -4856,7 +4857,7 @@ 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 +Following successful read, the `Promise` is fulfilled 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. @@ -4888,7 +4889,7 @@ added: v10.0.0 Asynchronously reads the entire contents of a file. -The `Promise` is resolved with the contents of the file. If no encoding is +The `Promise` is fulfilled with the contents of the file. If no encoding is specified (using `options.encoding`), the data is returned as a `Buffer` object. Otherwise, the data will be a string. @@ -4914,7 +4915,7 @@ added: Read from a file and write to an array of `ArrayBufferView`s -The `Promise` is resolved with an object containing a `bytesRead` property +The `Promise` is fulfilled with an object containing a `bytesRead` property identifying the number of bytes read, and a `buffers` property containing a reference to the `buffers` input. @@ -4946,7 +4947,7 @@ added: v10.0.0 * Returns: {Promise} -Asynchronous fsync(2). The `Promise` is resolved with no arguments upon +Asynchronous fsync(2). The `Promise` is fulflled with no arguments upon success. #### `filehandle.truncate(len)` @@ -4957,7 +4958,7 @@ added: v10.0.0 * `len` {integer} **Default:** `0` * Returns: {Promise} -Truncates the file then resolves the `Promise` with no arguments upon success. +Truncates the file then fulfills the `Promise` with no arguments upon success. If the file was larger than `len` bytes, only the first `len` bytes will be retained in the file. @@ -5028,9 +5029,9 @@ added: v10.0.0 * Returns: {Promise} Change the file system timestamps of the object referenced by the `FileHandle` -then resolves the `Promise` with no arguments upon success. +then fulfills the `Promise` with no arguments upon success. -This function does not work on AIX versions before 7.1, it will resolve the +This function does not work on AIX versions before 7.1, it will reject the `Promise` with an error using code `UV_ENOSYS`. #### `filehandle.write(buffer[, offset[, length[, position]]])` @@ -5055,7 +5056,7 @@ changes: Write `buffer` to the file. -The `Promise` is resolved with an object containing a `bytesWritten` property +The `Promise` is fulfilled with an object containing a `bytesWritten` property identifying the number of bytes written, and a `buffer` property containing a reference to the `buffer` written. @@ -5067,7 +5068,7 @@ should be written. If `typeof position !== 'number'`, the data will be written at the current position. See pwrite(2). It is unsafe to use `filehandle.write()` multiple times on the same file -without waiting for the `Promise` to be resolved (or rejected). For this +without waiting for the `Promise` to be fulfilled (or rejected). For this scenario, use [`fs.createWriteStream()`][]. On Linux, positional writes do not work when the file is opened in append mode. @@ -5096,7 +5097,7 @@ changes: Write `string` to the file. If `string` is not a string, or an object with an own `toString` function property, then an exception is thrown. -The `Promise` is resolved with an object containing a `bytesWritten` property +The `Promise` is fulfilled with an object containing a `bytesWritten` property identifying the number of bytes written, and a `buffer` property containing a reference to the `string` written. @@ -5107,7 +5108,7 @@ will be written at the current position. See pwrite(2). `encoding` is the expected string encoding. It is unsafe to use `filehandle.write()` multiple times on the same file -without waiting for the `Promise` to be resolved (or rejected). For this +without waiting for the `Promise` to be fulfilled (or rejected). For this scenario, use [`fs.createWriteStream()`][]. On Linux, positional writes do not work when the file is opened in append mode. @@ -5135,7 +5136,7 @@ changes: Asynchronously writes data to a file, replacing the file if it already exists. `data` can be a string, a buffer, or an object with an own `toString` function -property. The `Promise` is resolved with no arguments upon success. +property. The `Promise` is fulfilled with no arguments upon success. The `encoding` option is ignored if `data` is a buffer. @@ -5144,7 +5145,7 @@ If `options` is a string, then it specifies the encoding. The `FileHandle` has to support writing. It is unsafe to use `filehandle.writeFile()` multiple times on the same file -without waiting for the `Promise` to be resolved (or rejected). +without waiting for the `Promise` to be fulfilled (or rejected). If one or more `filehandle.write()` calls are made on a file handle and then a `filehandle.writeFile()` call is made, the data will be written from the @@ -5162,7 +5163,7 @@ added: v12.9.0 Write an array of `ArrayBufferView`s to the file. -The `Promise` is resolved with an object containing a `bytesWritten` property +The `Promise` is fulfilled with an object containing a `bytesWritten` property identifying the number of bytes written, and a `buffers` property containing a reference to the `buffers` input. @@ -5192,7 +5193,7 @@ checks to be performed. Check [File access constants][] for possible values of `mode`. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`). -If the accessibility check is successful, the `Promise` is resolved with no +If the accessibility check is successful, the `Promise` is fulfilled with no value. If any of the accessibility checks fail, the `Promise` is rejected with an `Error` object. The following example checks if the file `/etc/passwd` can be read and written by the current process. @@ -5227,7 +5228,7 @@ added: v10.0.0 Asynchronously append data to a file, creating the file if it does not yet exist. `data` can be a string or a [`Buffer`][]. The `Promise` will be -resolved with no arguments upon success. +fulfilled with no arguments upon success. If `options` is a string, then it specifies the encoding. @@ -5243,7 +5244,7 @@ added: v10.0.0 * `mode` {string|integer} * Returns: {Promise} -Changes the permissions of a file then resolves the `Promise` with no +Changes the permissions of a file then fulfills the `Promise` with no arguments upon succces. ### `fsPromises.chown(path, uid, gid)` @@ -5256,7 +5257,7 @@ added: v10.0.0 * `gid` {integer} * Returns: {Promise} -Changes the ownership of a file then resolves the `Promise` with no arguments +Changes the ownership of a file then fulfills the `Promise` with no arguments upon success. ### `fsPromises.copyFile(src, dest[, mode])` @@ -5275,7 +5276,7 @@ changes: * Returns: {Promise} Asynchronously copies `src` to `dest`. By default, `dest` is overwritten if it -already exists. The `Promise` will be resolved with no arguments upon success. +already exists. The `Promise` will be fulfilled with no arguments upon success. Node.js makes no guarantees about the atomicity of the copy operation. If an error occurs after the destination file has been opened for writing, Node.js @@ -5323,7 +5324,7 @@ deprecated: v10.0.0 * `mode` {integer} * Returns: {Promise} -Changes the permissions on a symbolic link then resolves the `Promise` with +Changes the permissions on a symbolic link then fulfills the `Promise` with no arguments upon success. This method is only implemented on macOS. ### `fsPromises.lchown(path, uid, gid)` @@ -5340,7 +5341,7 @@ changes: * `gid` {integer} * Returns: {Promise} -Changes the ownership on a symbolic link then resolves the `Promise` with +Changes the ownership on a symbolic link then fulfills the `Promise` with no arguments upon success. ### `fsPromises.lutimes(path, atime, mtime)` @@ -5360,7 +5361,7 @@ Changes the access and modification times of a file in the same way as symbolic link, then the link is not dereferenced: instead, the timestamps of the symbolic link itself are changed. -Upon success, the `Promise` is resolved without arguments. +Upon success, the `Promise` is fulfilled without arguments. ### `fsPromises.link(existingPath, newPath)`