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: add description for filehandle.write(string[, position[, encoding]]) #23224

Closed
wants to merge 1 commit into from
Closed

doc: add description for filehandle.write(string[, position[, encoding]]) #23224

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
31 changes: 31 additions & 0 deletions doc/api/fs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3939,6 +3939,37 @@ 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.

#### filehandle.write(string[, position[, encoding]])
<!-- YAML
added: v10.0.0
-->

* `string` {string}
* `position` {integer}
* `encoding` {string} **Default:** `'utf8'`
* Returns: {Promise}

Write `string` to the file. If `string` is not a string, then
the value will be coerced to one.

darahayes marked this conversation as resolved.
Show resolved Hide resolved
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 `string` written.

`position` refers to the offset from the beginning of the file where this data
should be written. If the type of `position` is not a `number` the data
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: a rejected promise is still resolved (and so is a promise following another promise) - fulfilled instead of resolved or "settled" instead of either would work here.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey there, I've addressed some other feedback but I haven't addressed this one yet. I did that for two reasons.

  1. This is the same wording used in other parts of the documentation. See the docs for the filehandle.write(buffer)
  2. I would argue that explicitly using the words resolved and rejected make sense in this context. If you're familiar with Promises, this makes sense. I would argue the same cannot exactly be said about the word fulfilled because it's not as commonly used when referring to Promises. (at least as far as I can tell). In my opinion that potentially introduces some ambiguity.

All that being said: I am happy to make the suggested changes here, as well as in the other parts of the same doc to ensure consistency.

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.

#### filehandle.writeFile(data, options)
<!-- YAML
added: v10.0.0
Expand Down