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.

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

doc: add ESM and CommonJS examples in fs documentation #52207

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
132 changes: 132 additions & 0 deletions doc/api/fs.md
Original file line number Diff line number Diff line change
Expand Up @@ -898,6 +898,21 @@ try {
}
```

```cjs
const { access, constants } = require('node:fs/promises');

async function checkAccess() {
try {
await access('/etc/passwd', constants.R_OK | constants.W_OK);
console.log('can access');
Comment on lines +906 to +907
Copy link
Contributor Author

Choose a reason for hiding this comment

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

This doesn't seem right to me, actually. Specifically, I think the console.log() can trigger despite the access failing.

} catch {
console.error('cannot access');
}
}

checkAccess();
```

Using `fsPromises.access()` to check for the accessibility of a file before
calling `fsPromises.open()` is not recommended. Doing so introduces a race
condition, since other processes may change the file's state between the two
Expand Down Expand Up @@ -937,6 +952,30 @@ for more details.
The `path` may be specified as a {FileHandle} that has been opened
for appending (using `fsPromises.open()`).

```mjs
import { appendFile } from 'node:fs/promises';

try {
await appendFile('message.txt', 'data to append');
} catch {
console.error('The file could not be appended!');
}
```

```cjs
const { appendFile } = require('node:fs/promises');

async function appendMessagesFile() {
try {
await appendFile('message.txt', 'data to append');
} catch {
console.error('The file could not be appended!');
}
}

appendMessagesFile();
```

### `fsPromises.chmod(path, mode)`

<!-- YAML
Expand All @@ -949,6 +988,30 @@ added: v10.0.0

Changes the permissions of a file.

```mjs
import { chmod } from 'node:fs/promises';

try {
await chmod('my_file.txt', 0o775).then(console.log('The permissions for file "my_file.txt" have been changed!'));
Copy link
Contributor

Choose a reason for hiding this comment

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

IMO it's much more readable as two separate expressions

Suggested change
await chmod('my_file.txt', 0o775).then(console.log('The permissions for file "my_file.txt" have been changed!'));
await chmod('my_file.txt', 0o775);
console.log('The permissions for file "my_file.txt" have been changed!');

} catch {
console.error('The permissions for file "my_file.txt" failed to change!');
}
```

```cjs
const { chmod } = require('node:fs/promises');

async function changeFilePermissions() {
try {
await chmod('my_file.txt', 0o775).then(console.log('The permissions for file "my_file.txt" have been changed!'));
} catch {
console.error('The permissions for file "my_file.txt" failed to change!');
}
}

changeFilePermissions();
```

### `fsPromises.chown(path, uid, gid)`

<!-- YAML
Expand All @@ -962,6 +1025,38 @@ added: v10.0.0

Changes the ownership of a file.

```mjs
import { chown } from 'node:fs/promises';
import { getuid, getgid } from 'node:process';

const uid = getuid();
const gid = getgid();

try {
await chown('my_file.txt', uid, gid).then(console.log(`Successfully ran chown on my_file.txt to UID ${uid} and GID ${gid}!`));
} catch {
console.error('Failed to chown my_file.txt!');
}
```

```cjs
const { chown } = require('node:fs/promises');
const { getuid, getgid } = require('node:process');

async function chownMyFile() {
const uid = getuid();
const gid = getgid();

try {
await chown('my_file.txt', uid, gid).then(console.log(`Successfully ran chown on my_file.txt to UID ${uid} and GID ${gid}!`));
} catch {
console.error('Failed to chown my_file.txt!');
}
}

chownMyFile();
```

### `fsPromises.copyFile(src, dest[, mode])`

<!-- YAML
Expand Down Expand Up @@ -2239,6 +2334,15 @@ chmod('my_file.txt', 0o775, (err) => {
});
```

```cjs
const { chmod } = require('node:fs');

chmod('my_file.txt', 0o775, (err) => {
if (err) throw err;
console.log('The permissions for file "my_file.txt" have been changed!');
});
```

#### File modes

The `mode` argument used in both the `fs.chmod()` and `fs.chmodSync()`
Expand Down Expand Up @@ -2324,6 +2428,34 @@ possible exception are given to the completion callback.

See the POSIX chown(2) documentation for more detail.

```mjs
import { chown } from 'node:fs';
import { getuid, getgid } from 'node:process';

const uid = getuid();
const gid = getgid();

chown('my_file.txt', uid, gid, (err) => {
if (err) throw err;

console.log(`Successfully ran chown on my_file.txt to UID ${uid} and GID ${gid}!`);
});
```

```cjs
const { chown } = require('node:fs');
const { getuid, getgid } = require('node:process');

const uid = getuid();
const gid = getgid();

chown('my_file.txt', uid, gid, (err) => {
if (err) throw err;

console.log(`Successfully ran chown on my_file.txt to UID ${uid} and GID ${gid}!`);
});
```

### `fs.close(fd[, callback])`

<!-- YAML
Expand Down