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

Jump to bottom

doc: clarify some default values in fs.md #42892

Merged
merged 3 commits into from
May 2, 2022
Merged

doc: clarify some default values in fs.md #42892

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
18137b2
doc: clarify some default values in fs.md
LiviaMedeiros Apr 28, 2022
76e639c
squash: declare some values as nullable in fs.js
LiviaMedeiros Apr 29, 2022
0e071a7
squash: document position in fs.readSync as optional
LiviaMedeiros Apr 30, 2022
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
66 changes: 33 additions & 33 deletions doc/api/fs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -374,7 +374,7 @@ added: v10.0.0
file data read.
* `offset` {integer} The location in the buffer at which to start filling.
* `length` {integer} The number of bytes to read.
* `position` {integer} The location where to begin reading data from the
* `position` {integer|null} The location where to begin reading data from the
file. If `null`, data will be read from the current file position, and
the position will be updated. If `position` is an integer, the current
file position will remain unchanged.
Expand Down Expand Up @@ -403,7 +403,7 @@ added:
**Default:** `0`
* `length` {integer} The number of bytes to read. **Default:**
`buffer.byteLength - offset`
* `position` {integer} The location where to begin reading data from the
* `position` {integer|null} The location where to begin reading data from the
file. If `null`, data will be read from the current file position, and
the position will be updated. If `position` is an integer, the current
file position will remain unchanged. **Default:**: `null`
Expand Down Expand Up @@ -497,9 +497,9 @@ added:
-->

* `buffers` {Buffer\[]|TypedArray\[]|DataView\[]}
* `position` {integer} The offset from the beginning of the file where the data
should be read from. If `position` is not a `number`, the data will be read
from the current position.
* `position` {integer|null} The offset from the beginning of the file where
the data should be read from. If `position` is not a `number`, the data will
be read from the current position. **Default:** `null`
* Returns: {Promise} Fulfills upon success an object containing two properties:
* `bytesRead` {integer} the number of bytes read
* `buffers` {Buffer\[]|TypedArray\[]|DataView\[]} property containing
Expand Down Expand Up @@ -597,10 +597,10 @@ changes:
to write begins. **Default:** `0`
* `length` {integer} The number of bytes from `buffer` to write. **Default:**
`buffer.byteLength - offset`
* `position` {integer} The offset from the beginning of the file where the
* `position` {integer|null} The offset from the beginning of the file where the
data from `buffer` should be written. If `position` is not a `number`,
the data will be written at the current position. See the POSIX pwrite(2)
documentation for more detail.
documentation for more detail. **Default:** `null`
* Returns: {Promise}

Write `buffer` to the file.
Expand Down Expand Up @@ -631,10 +631,10 @@ changes:
-->

* `string` {string}
* `position` {integer} The offset from the beginning of the file where the
* `position` {integer|null} The offset from the beginning of the file where the
data from `string` should be written. If `position` is not a `number` the
data will be written at the current position. See the POSIX pwrite(2)
documentation for more detail.
documentation for more detail. **Default:** `null`
* `encoding` {string} The expected string encoding. **Default:** `'utf8'`
* Returns: {Promise}

Expand Down Expand Up @@ -699,9 +699,9 @@ added: v12.9.0
-->

* `buffers` {Buffer\[]|TypedArray\[]|DataView\[]}
* `position` {integer} The offset from the beginning of the file where the
* `position` {integer|null} The offset from the beginning of the file where the
data from `buffers` should be written. If `position` is not a `number`,
the data will be written at the current position.
the data will be written at the current position. **Default:** `null`
* Returns: {Promise}

Write an array of {ArrayBufferView}s to the file.
Expand Down Expand Up @@ -3198,7 +3198,7 @@ changes:
written to.
* `offset` {integer} The position in `buffer` to write the data to.
* `length` {integer} The number of bytes to read.
* `position` {integer|bigint} Specifies where to begin reading from in the
* `position` {integer|bigint|null} Specifies where to begin reading from in the
file. If `position` is `null` or `-1 `, 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 be unchanged.
Expand Down Expand Up @@ -3237,7 +3237,7 @@ changes:
* `buffer` {Buffer|TypedArray|DataView} **Default:** `Buffer.alloc(16384)`
* `offset` {integer} **Default:** `0`
* `length` {integer} **Default:** `buffer.byteLength - offset`
* `position` {integer|bigint} **Default:** `null`
* `position` {integer|bigint|null} **Default:** `null`
* `callback` {Function}
* `err` {Error}
* `bytesRead` {integer}
Expand Down Expand Up @@ -3502,7 +3502,7 @@ changes:

* `fd` {integer}
* `buffers` {ArrayBufferView\[]}
* `position` {integer}
* `position` {integer|null} **Default:** `null`
* `callback` {Function}
* `err` {Error}
* `bytesRead` {integer}
Expand Down Expand Up @@ -3924,7 +3924,7 @@ changes:

* `target` {string|Buffer|URL}
* `path` {string|Buffer|URL}
* `type` {string}
* `type` {string|null} **Default:** `null`
* `callback` {Function}
* `err` {Error}

Expand All @@ -3935,8 +3935,8 @@ See the POSIX symlink(2) documentation for more details.

The `type` argument is only available on Windows and ignored on other platforms.
It can be set to `'dir'`, `'file'`, or `'junction'`. If the `type` argument is
not set, Node.js will autodetect `target` type and use `'file'` or `'dir'`. If
the `target` does not exist, `'file'` will be used. Windows junction points
not a string, Node.js will autodetect `target` type and use `'file'` or `'dir'`.
If the `target` does not exist, `'file'` will be used. Windows junction points
require the destination path to be absolute. When using `'junction'`, the
`target` argument will automatically be normalized to absolute path.

Expand Down Expand Up @@ -4363,9 +4363,9 @@ changes:

* `fd` {integer}
* `buffer` {Buffer|TypedArray|DataView}
* `offset` {integer}
* `length` {integer}
* `position` {integer}
* `offset` {integer} **Default:** `0`
* `length` {integer} **Default:** `buffer.byteLength - offset`
* `position` {integer|null} **Default:** `null`
* `callback` {Function}
* `err` {Error}
* `bytesWritten` {integer}
Expand Down Expand Up @@ -4426,7 +4426,7 @@ changes:

* `fd` {integer}
* `string` {string|Object}
* `position` {integer}
* `position` {integer|null} **Default:** `null`
* `encoding` {string} **Default:** `'utf8'`
* `callback` {Function}
* `err` {Error}
Expand Down Expand Up @@ -4627,7 +4627,7 @@ changes:

* `fd` {integer}
* `buffers` {ArrayBufferView\[]}
* `position` {integer}
* `position` {integer|null} **Default:** `null`
* `callback` {Function}
* `err` {Error}
* `bytesWritten` {integer}
Expand Down Expand Up @@ -5344,7 +5344,7 @@ object with an `encoding` property specifying the character encoding to use for
the link path returned. If the `encoding` is set to `'buffer'`,
the link path returned will be passed as a {Buffer} object.

### `fs.readSync(fd, buffer, offset, length, position)`
### `fs.readSync(fd, buffer, offset, length[, position])`

<!-- YAML
added: v0.1.21
Expand All @@ -5362,7 +5362,7 @@ changes:
* `buffer` {Buffer|TypedArray|DataView}
* `offset` {integer}
* `length` {integer}
* `position` {integer|bigint}
* `position` {integer|bigint|null} **Default:** `null`
* Returns: {number}

Returns the number of `bytesRead`.
Expand Down Expand Up @@ -5390,7 +5390,7 @@ changes:
* `options` {Object}
* `offset` {integer} **Default:** `0`
* `length` {integer} **Default:** `buffer.byteLength - offset`
* `position` {integer|bigint} **Default:** `null`
* `position` {integer|bigint|null} **Default:** `null`
* Returns: {number}

Returns the number of `bytesRead`.
Expand All @@ -5411,7 +5411,7 @@ added:

* `fd` {integer}
* `buffers` {ArrayBufferView\[]}
* `position` {integer}
* `position` {integer|null} **Default:** `null`
* Returns: {number} The number of bytes read.

For detailed information, see the documentation of the asynchronous version of
Expand Down Expand Up @@ -5635,7 +5635,7 @@ changes:

* `target` {string|Buffer|URL}
* `path` {string|Buffer|URL}
* `type` {string}
* `type` {string|null} **Default:** `null`

Returns `undefined`.

Expand Down Expand Up @@ -5767,9 +5767,9 @@ changes:

* `fd` {integer}
* `buffer` {Buffer|TypedArray|DataView}
* `offset` {integer}
* `length` {integer}
* `position` {integer}
* `offset` {integer} **Default:** `0`
* `length` {integer} **Default:** `buffer.byteLength - offset`
* `position` {integer|null} **Default:** `null`
* Returns: {number} The number of bytes written.

For detailed information, see the documentation of the asynchronous version of
Expand All @@ -5791,8 +5791,8 @@ changes:

* `fd` {integer}
* `string` {string}
* `position` {integer}
* `encoding` {string}
* `position` {integer|null} **Default:** `null`
* `encoding` {string} **Default:** `'utf8'`
* Returns: {number} The number of bytes written.

For detailed information, see the documentation of the asynchronous version of
Expand All @@ -5806,7 +5806,7 @@ added: v12.9.0

* `fd` {integer}
* `buffers` {ArrayBufferView\[]}
* `position` {integer}
* `position` {integer|null} **Default:** `null`
* Returns: {number} The number of bytes written.

For detailed information, see the documentation of the asynchronous version of
Expand Down
20 changes: 10 additions & 10 deletions lib/fs.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -597,7 +597,7 @@ function openSync(path, flags, mode) {
* @param {Buffer | TypedArray | DataView} buffer
* @param {number} offset
* @param {number} length
* @param {number | bigint} position
* @param {number | bigint | null} position
* @param {(
* err?: Error,
* bytesRead?: number,
Expand Down Expand Up @@ -682,7 +682,7 @@ ObjectDefineProperty(read, internalUtil.customPromisifyArgs,
* @param {{
* offset?: number;
* length?: number;
* position?: number | bigint;
* position?: number | bigint | null;
* }} [offset]
* @returns {number}
*/
Expand Down Expand Up @@ -738,7 +738,7 @@ function readSync(fd, buffer, offset, length, position) {
* and writes to an array of `ArrayBufferView`s.
* @param {number} fd
* @param {ArrayBufferView[]} buffers
* @param {number} [position]
* @param {number | null} [position]
* @param {(
* err?: Error,
* bytesRead?: number,
Expand Down Expand Up @@ -773,7 +773,7 @@ ObjectDefineProperty(readv, internalUtil.customPromisifyArgs,
* of `ArrayBufferView`s.
* @param {number} fd
* @param {ArrayBufferView[]} buffers
* @param {number} [position]
* @param {number | null} [position]
* @returns {number}
*/
function readvSync(fd, buffers, position) {
Expand All @@ -796,7 +796,7 @@ function readvSync(fd, buffers, position) {
* @param {Buffer | TypedArray | DataView | string | object} buffer
* @param {number} [offset]
* @param {number} [length]
* @param {number} [position]
* @param {number | null} [position]
* @param {(
* err?: Error,
* bytesWritten?: number;
Expand Down Expand Up @@ -864,7 +864,7 @@ ObjectDefineProperty(write, internalUtil.customPromisifyArgs,
* @param {Buffer | TypedArray | DataView | string} buffer
* @param {number} [offset]
* @param {number} [length]
* @param {number} [position]
* @param {number | null} [position]
* @returns {number}
*/
function writeSync(fd, buffer, offset, length, position) {
Expand Down Expand Up @@ -902,7 +902,7 @@ function writeSync(fd, buffer, offset, length, position) {
* specified `fd` (file descriptor).
* @param {number} fd
* @param {ArrayBufferView[]} buffers
* @param {number} [position]
* @param {number | null} [position]
* @param {(
* err?: Error,
* bytesWritten?: number,
Expand Down Expand Up @@ -943,7 +943,7 @@ ObjectDefineProperty(writev, internalUtil.customPromisifyArgs, {
* to the specified `fd` (file descriptor).
* @param {number} fd
* @param {ArrayBufferView[]} buffers
* @param {number} [position]
* @param {number | null} [position]
* @returns {number}
*/
function writevSync(fd, buffers, position) {
Expand Down Expand Up @@ -1601,7 +1601,7 @@ function readlinkSync(path, options) {
* Creates the link called `path` pointing to `target`.
* @param {string | Buffer | URL} target
* @param {string | Buffer | URL} path
* @param {string} [type_]
* @param {string | null} [type_]
* @param {(err?: Error) => any} callback_
* @returns {void}
*/
Expand Down Expand Up @@ -1654,7 +1654,7 @@ function symlink(target, path, type_, callback_) {
* pointing to `target`.
* @param {string | Buffer | URL} target
* @param {string | Buffer | URL} path
* @param {string} [type]
* @param {string | null} [type]
* @returns {void}
*/
function symlinkSync(target, path, type) {
Expand Down