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

doc: improve fs code example quality #46948

Closed
wants to merge 3 commits into from
Closed

doc: improve fs code example quality #46948

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
51ba66d
doc: improve fs code example quality
jakecastelli Mar 4, 2023
7ba5500
fix: add missing optional chaining operator
jakecastelli Mar 4, 2023
67da4a3
fixup
jakecastelli Mar 5, 2023
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
32 changes: 19 additions & 13 deletions doc/api/fs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1117,7 +1117,7 @@ try {

```cjs
const { mkdir } = require('node:fs/promises');
const { resolve, join } = require('node:path');
const { join } = require('node:path');

async function makeDirectory() {
const projectFolder = join(__dirname, 'test', 'project');
Expand Down Expand Up @@ -1159,9 +1159,11 @@ object with an `encoding` property specifying the character encoding to use.

```mjs
import { mkdtemp } from 'node:fs/promises';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

try {
await mkdtemp(path.join(os.tmpdir(), 'foo-'));
await mkdtemp(join(tmpdir(), 'foo-'));
} catch (err) {
console.error(err);
}
Expand Down Expand Up @@ -3237,8 +3239,10 @@ object with an `encoding` property specifying the character encoding to use.

```mjs
import { mkdtemp } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

mkdtemp(path.join(os.tmpdir(), 'foo-'), (err, directory) => {
mkdtemp(join(tmpdir(), 'foo-'), (err, directory) => {
if (err) throw err;
console.log(directory);
// Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2
Expand Down Expand Up @@ -7542,6 +7546,8 @@ For example, the following is prone to error because the `fs.stat()`
operation might complete before the `fs.rename()` operation:

```js
const fs = require('node:fs');
Copy link
Contributor

Choose a reason for hiding this comment

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

We would typically need to have two examples here, one ESM and one CJS. (doesn't have to block this PR from landing, but it'd need to happen at some point)

Copy link
Member Author

Choose a reason for hiding this comment

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

No problems, once this PR lands I can work on another PR to make sure all of the fs code examples have js flavor 👌 (at the moment there are many of the examples in fs missing them)


fs.rename('/tmp/hello', '/tmp/world', (err) => {
if (err) throw err;
console.log('renamed complete');
Expand All @@ -7558,12 +7564,12 @@ of one before invoking the other:
```mjs
import { rename, stat } from 'node:fs/promises';

const from = '/tmp/hello';
const to = '/tmp/world';
const fromDir = '/tmp/hello';
const toDir = '/tmp/world';
Copy link
Contributor

Choose a reason for hiding this comment

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

Does this imply that /tmp/hello and /tmp/world are directories? I think, something like

Suggested change
const fromDir = '/tmp/hello';
const toDir = '/tmp/world';
const fromPath = '/tmp/hello';
const toPath = '/tmp/world';

or

Suggested change
const fromDir = '/tmp/hello';
const toDir = '/tmp/world';
const oldPath = '/tmp/hello';
const newPath = '/tmp/world';

would be less confusing.

Copy link
Member Author

Choose a reason for hiding this comment

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

I agree 👍 thanks!


try {
await rename(from, to);
const stats = await stat(to);
await rename(fromDir, toDir);
const stats = await stat(toDir);
console.log(`stats: ${JSON.stringify(stats)}`);
} catch (error) {
console.error('there was an error:', error.message);
Expand All @@ -7573,10 +7579,10 @@ try {
```cjs
const { rename, stat } = require('node:fs/promises');

(async function(from, to) {
(async function(fromDir, toDir) {
try {
await rename(from, to);
const stats = await stat(to);
await rename(fromDir, toDir);
const stats = await stat(toDir);
console.log(`stats: ${JSON.stringify(stats)}`);
} catch (error) {
console.error('there was an error:', error.message);
Expand Down Expand Up @@ -7632,7 +7638,7 @@ try {
fd = await open('/open/some/file.txt', 'r');
// Do something with the file
} finally {
await fd.close();
await fd?.close();
}
```

Expand All @@ -7646,7 +7652,7 @@ try {
fd = await open('file.txt', 'r');
// Do something with the file
} finally {
await fd.close();
await fd?.close();
}
```

Expand Down Expand Up @@ -7761,7 +7767,7 @@ try {
fd = await open(Buffer.from('/open/some/file.txt'), 'r');
// Do something with the file
} finally {
await fd.close();
await fd?.close();
}
```

Expand Down