From e5744a379152f16f138fcbc03b2573ce3377f414 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Thu, 4 Mar 2021 22:31:49 +0100 Subject: [PATCH] doc: change lang info string in fs JS snippets Refs: https://github.com/nodejs/remark-preset-lint-node/pull/176 PR-URL: https://github.com/nodejs/node/pull/37605 Refs: https://github.com/nodejs/node/pull/37162 Reviewed-By: Rich Trott Reviewed-By: Danielle Adams Reviewed-By: Darshan Sen Reviewed-By: James M Snell Reviewed-By: Benjamin Gruenbaum --- doc/api/fs.md | 158 +++++++++++++++++++++++++------------------------- 1 file changed, 79 insertions(+), 79 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 1a501233a7b1fd..b510cdd7244354 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -13,24 +13,24 @@ way modeled on standard POSIX functions. To use the promise-based APIs: -```js esm +```mjs // Using ESM Module syntax: import * as fs from 'fs/promises'; ``` -```js cjs +```cjs // Using CommonJS syntax: const fs = require('fs/promises'); ``` To use the callback and sync APIs: -```js esm +```mjs // Using ESM Module syntax: import * as fs from 'fs'; ``` -```js cjs +```cjs // Using CommonJS syntax: const fs = require('fs'); ``` @@ -43,7 +43,7 @@ forms, and are accessible using both CommonJS syntax and ES6 Modules (ESM). Promise-based operations return a promise that is fulfilled when the asynchronous operation is complete. -```js esm +```mjs // Using ESM Module syntax: import { unlink } from 'fs/promises'; @@ -55,7 +55,7 @@ try { } ``` -```js cjs +```cjs // Using CommonJS syntax const { unlink } = require('fs/promises'); @@ -77,7 +77,7 @@ the completion callback depend on the method, but the first argument is always reserved for an exception. If the operation is completed successfully, then the first argument is `null` or `undefined`. -```js esm +```mjs // Using ESM syntax import { unlink } from 'fs'; @@ -87,7 +87,7 @@ unlink('/tmp/hello', (err) => { }); ``` -```js cjs +```cjs // Using CommonJS syntax const { unlink } = require('fs'); @@ -107,7 +107,7 @@ The synchronous APIs block the Node.js event loop and further JavaScript execution until the operation is complete. Exceptions are thrown immediately and can be handled using `try…catch`, or can be allowed to bubble up. -```js esm +```mjs // Using ESM syntax import { unlinkSync } from 'fs'; @@ -119,7 +119,7 @@ try { } ``` -```js cjs +```cjs // Using CommonJS syntax const { unlinkSync } = require('fs'); @@ -221,7 +221,7 @@ added: v10.0.0 Closes the file handle after waiting for any pending operation on the handle to complete. -```js esm +```mjs import { open } from 'fs/promises'; let filehandle; @@ -381,7 +381,7 @@ retained in the file. The following example retains only the first four bytes of the file: -```js esm +```mjs import { open } from 'fs/promises'; let filehandle = null; @@ -571,7 +571,7 @@ 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. -```js esm +```mjs import { access } from 'fs/promises'; import { constants } from 'fs'; @@ -667,7 +667,7 @@ No guarantees are made about the atomicity of the copy operation. If an error occurs after the destination file has been opened for writing, an attempt will be made to remove the destination. -```js esm +```mjs import { constants } from 'fs'; import { copyFile } from 'fs/promises'; @@ -805,7 +805,7 @@ replace trailing `X` characters in `prefix` with random characters. The optional `options` argument can be a string specifying an encoding, or an object with an `encoding` property specifying the character encoding to use. -```js esm +```mjs import { mkdtemp } from 'fs/promises'; try { @@ -876,7 +876,7 @@ directory and subsequent read operations. Example using async iteration: -```js esm +```mjs import { opendir } from 'fs/promises'; try { @@ -914,7 +914,7 @@ will be passed as {Buffer} objects. If `options.withFileTypes` is set to `true`, the resolved array will contain {fs.Dirent} objects. -```js esm +```mjs import { readdir } from 'fs/promises'; try { @@ -958,7 +958,7 @@ returned. It is possible to abort an ongoing `readFile` using an {AbortSignal}. If a request is aborted the promise returned is rejected with an `AbortError`: -```js esm +```mjs import { readFile } from 'fs/promises'; try { @@ -1228,7 +1228,7 @@ It is possible to use an {AbortSignal} to cancel an `fsPromises.writeFile()`. Cancelation is "best effort", and some amount of data is likely still to be written. -```js esm +```mjs import { writeFile } from 'fs/promises'; try { @@ -1290,7 +1290,7 @@ a possible error argument. If any of the accessibility checks fail, the error argument will be an `Error` object. The following examples check if `package.json` exists, and if it is readable or writable. -```js esm +```mjs import { access, constants } from 'fs'; const file = 'package.json'; @@ -1329,7 +1329,7 @@ file directly and handle the error raised if the file is not accessible. **write (NOT RECOMMENDED)** -```js esm +```mjs import { access, open, close } from 'fs'; access('myfile', (err) => { @@ -1354,7 +1354,7 @@ access('myfile', (err) => { **write (RECOMMENDED)** -```js esm +```mjs import { open, close } from 'fs'; open('myfile', 'wx', (err, fd) => { @@ -1379,7 +1379,7 @@ open('myfile', 'wx', (err, fd) => { **read (NOT RECOMMENDED)** -```js esm +```mjs import { access, open, close } from 'fs'; access('myfile', (err) => { if (err) { @@ -1407,7 +1407,7 @@ access('myfile', (err) => { **read (RECOMMENDED)** -```js +```mjs import { open, close } from 'fs'; open('myfile', 'r', (err, fd) => { @@ -1475,7 +1475,7 @@ changes: Asynchronously append data to a file, creating the file if it does not yet exist. `data` can be a string or a {Buffer}. -```js esm +```mjs import { appendFile } from 'fs'; appendFile('message.txt', 'data to append', (err) => { @@ -1486,7 +1486,7 @@ appendFile('message.txt', 'data to append', (err) => { If `options` is a string, then it specifies the encoding: -```js esm +```mjs import { appendFile } from 'fs'; appendFile('message.txt', 'data to append', 'utf8', callback); @@ -1496,7 +1496,7 @@ The `path` may be specified as a numeric file descriptor that has been opened for appending (using `fs.open()` or `fs.openSync()`). The file descriptor will not be closed automatically. -```js esm +```mjs import { open, close, appendFile } from 'fs'; function closeFd(fd) { @@ -1548,7 +1548,7 @@ possible exception are given to the completion callback. See the POSIX chmod(2) documentation for more detail. -```js esm +```mjs import { chmod } from 'fs'; chmod('my_file.txt', 0o775, (err) => { @@ -1700,7 +1700,7 @@ OR of two or more values (e.g. create a copy-on-write reflink. If the platform does not support copy-on-write, then the operation will fail. -```js esm +```mjs import { copyFile, constants } from 'fs'; function callback(err) { @@ -1792,7 +1792,7 @@ By providing the `fs` option, it is possible to override the corresponding `fs` implementations for `open`, `read`, and `close`. When providing the `fs` option, overrides for `open`, `read`, and `close` are required. -```js esm +```mjs import { createReadStream } from 'fs'; // Create a stream from some character device. @@ -1820,7 +1820,7 @@ file was created. An example to read the last 10 bytes of a file which is 100 bytes long: -```js esm +```mjs import { createReadStream } from 'fs'; createReadStream('sample.txt', { start: 90, end: 99 }); @@ -1921,7 +1921,7 @@ changes: Test whether or not the given path exists by checking with the file system. Then call the `callback` argument with either true or false: -```js esm +```mjs import { exists } from 'fs'; exists('/etc/passwd', (e) => { @@ -1943,7 +1943,7 @@ file directly and handle the error raised if the file does not exist. **write (NOT RECOMMENDED)** -```js esm +```mjs import { exists, open, close } from 'fs'; exists('myfile', (e) => { @@ -1967,7 +1967,7 @@ exists('myfile', (e) => { **write (RECOMMENDED)** -```js esm +```mjs import { open, close } from 'fs'; open('myfile', 'wx', (err, fd) => { if (err) { @@ -1991,7 +1991,7 @@ open('myfile', 'wx', (err, fd) => { **read (NOT RECOMMENDED)** -```js esm +```mjs import { open, close, exists } from 'fs'; exists('myfile', (e) => { @@ -2015,7 +2015,7 @@ exists('myfile', (e) => { **read (RECOMMENDED)** -```js esm +```mjs import { open, close } from 'fs'; open('myfile', 'r', (err, fd) => { @@ -2201,7 +2201,7 @@ the first `len` bytes will be retained in the file. For example, the following program retains only the first four bytes of the file: -```js esm +```mjs import { open, close, ftruncate } from 'fs'; function closeFd(fd) { @@ -2447,7 +2447,7 @@ property indicating whether parent directories should be created. Calling `fs.mkdir()` when `path` is a directory that exists results in an error only when `recursive` is false. -```js esm +```mjs import { mkdir } from 'fs'; // Creates /tmp/a/apple, regardless of whether `/tmp` and /tmp/a exist. @@ -2459,7 +2459,7 @@ mkdir('/tmp/a/apple', { recursive: true }, (err) => { On Windows, using `fs.mkdir()` on the root directory even with recursion will result in an error: -```js esm +```mjs import { mkdir } from 'fs'; mkdir('/', { recursive: true }, (err) => { @@ -2507,7 +2507,7 @@ parameter. The optional `options` argument can be a string specifying an encoding, or an object with an `encoding` property specifying the character encoding to use. -```js esm +```mjs import { mkdtemp } from 'fs'; mkdtemp(path.join(os.tmpdir(), 'foo-'), (err, directory) => { @@ -2523,7 +2523,7 @@ intention is to create a temporary directory *within* `/tmp`, the `prefix` must end with a trailing platform-specific path separator (`require('path').sep`). -```js esm +```mjs import { tmpdir } from 'os'; import { mkdtemp } from 'fs'; @@ -2774,7 +2774,7 @@ changes: Asynchronously reads the entire contents of a file. -```js esm +```mjs import { readFile } from 'fs'; readFile('/etc/passwd', (err, data) => { @@ -2790,7 +2790,7 @@ If no encoding is specified, then the raw buffer is returned. If `options` is a string, then it specifies the encoding: -```js esm +```mjs import { readFile } from 'fs'; readFile('/etc/passwd', 'utf8', callback); @@ -2801,7 +2801,7 @@ When the path is a directory, the behavior of `fs.readFile()` and error will be returned. On FreeBSD, a representation of the directory's contents will be returned. -```js esm +```mjs import { readFile } from 'fs'; // macOS, Linux, and Windows @@ -2818,7 +2818,7 @@ readFile('', (err, data) => { It is possible to abort an ongoing request using an `AbortSignal`. If a request is aborted the callback is called with an `AbortError`: -```js esm +```mjs import { readFile } from 'fs'; const controller = new AbortController(); @@ -3051,7 +3051,7 @@ given to the completion callback. See also: rename(2). -```js esm +```mjs import { rename } from 'fs'; rename('oldFile.txt', 'newFile.txt', (err) => { @@ -3198,7 +3198,7 @@ For example, given the following directory structure: The next program will check for the stats of the given paths: -```js esm +```mjs import { stat } from 'fs'; const pathsToCheck = ['./txtDir', './txtDir/file.txt']; @@ -3293,7 +3293,7 @@ require the destination path to be absolute. When using `'junction'`, the Relative targets are relative to the link’s parent directory. -```js esm +```mjs import { symlink } from 'fs'; symlink('./mew', './example/mewtwo', callback); @@ -3362,7 +3362,7 @@ changes: Asynchronously removes a file or symbolic link. No arguments other than a possible exception are given to the completion callback. -```js esm +```mjs import { unlink } from 'fs'; // Assuming that 'path/file.txt' is a regular file. unlink('path/file.txt', (err) => { @@ -3551,7 +3551,7 @@ macOS, Windows, and AIX. Even on supported platforms, `filename` is not always guaranteed to be provided. Therefore, don't assume that `filename` argument is always provided in the callback, and have some fallback logic if it is `null`. -```js esm +```mjs import { watch } from 'fs'; watch('somedir', (eventType, filename) => { console.log(`event type is: ${eventType}`); @@ -3598,7 +3598,7 @@ target should be polled in milliseconds. The `listener` gets two arguments the current stat object and the previous stat object: -```js esm +```mjs import { watchFile } from 'fs'; watchFile('message.text', (curr, prev) => { @@ -3818,7 +3818,7 @@ a file descriptor. The `encoding` option is ignored if `data` is a buffer. If `data` is a normal object, it must have an own `toString` function property. -```js esm +```mjs import { writeFile } from 'fs'; const data = new Uint8Array(Buffer.from('Hello Node.js')); @@ -3830,7 +3830,7 @@ writeFile('message.txt', data, (err) => { If `options` is a string, then it specifies the encoding: -```js esm +```mjs import { writeFile } from 'fs'; writeFile('message.txt', 'Hello Node.js', 'utf8', callback); @@ -3848,7 +3848,7 @@ It is possible to use an {AbortSignal} to cancel an `fs.writeFile()`. Cancelation is "best effort", and some amount of data is likely still to be written. -```js esm +```mjs import { writeFile } from 'fs'; const controller = new AbortController(); @@ -3869,7 +3869,7 @@ system requests but rather the internal buffering `fs.writeFile` performs. When `file` is a file descriptor, the behavior is almost identical to directly calling `fs.write()` like: -```js esm +```mjs import { write } from 'fs'; write(fd, Buffer.from(data, options.encoding), callback); @@ -3953,7 +3953,7 @@ the bitwise OR of two or more values If any of the accessibility checks fail, an `Error` will be thrown. Otherwise, the method will return `undefined`. -```js esm +```mjs import { accessSync, constants } from 'fs'; try { @@ -3986,7 +3986,7 @@ changes: Synchronously append data to a file, creating the file if it does not yet exist. `data` can be a string or a {Buffer}. -```js esm +```mjs import { appendFileSync } from 'fs'; try { @@ -3999,7 +3999,7 @@ try { If `options` is a string, then it specifies the encoding: -```js esm +```mjs import { appendFileSync } from 'fs'; appendFileSync('message.txt', 'data to append', 'utf8'); @@ -4009,7 +4009,7 @@ The `path` may be specified as a numeric file descriptor that has been opened for appending (using `fs.open()` or `fs.openSync()`). The file descriptor will not be closed automatically. -```js esm +```mjs import { openSync, closeSync, appendFileSync } from 'fs'; let fd; @@ -4109,7 +4109,7 @@ OR of two or more values (e.g. create a copy-on-write reflink. If the platform does not support copy-on-write, then the operation will fail. -```js esm +```mjs import { copyFileSync, constants } from 'fs'; // destination.txt will be created or overwritten by default. @@ -4142,7 +4142,7 @@ this API: [`fs.exists()`][]. parameter to `fs.exists()` accepts parameters that are inconsistent with other Node.js callbacks. `fs.existsSync()` does not use a callback. -```js esm +```mjs import { existsSync } from 'fs'; if (existsSync('/etc/passwd')) @@ -4504,7 +4504,7 @@ string. Otherwise it returns a buffer. Similar to [`fs.readFile()`][], when the path is a directory, the behavior of `fs.readFileSync()` is platform-specific. -```js esm +```mjs import { readFileSync } from 'fs'; // macOS, Linux, and Windows @@ -4977,7 +4977,7 @@ A class representing a directory stream. Created by [`fs.opendir()`][], [`fs.opendirSync()`][], or [`fsPromises.opendir()`][]. -```js esm +```mjs import { opendir } from 'fs/promises'; try { @@ -5226,7 +5226,7 @@ support. If `filename` is provided, it will be provided as a {Buffer} if `fs.watch()` is called with its `encoding` option set to `'buffer'`, otherwise `filename` will be a UTF-8 string. -```js esm +```mjs import { watch } from 'fs'; // Example when handled through fs.watch() listener watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => { @@ -5848,7 +5848,7 @@ To use more than one constant, use the bitwise OR `|` operator. Example: -```js esm +```mjs import { open, constants } from 'fs'; const { @@ -6145,7 +6145,7 @@ fs.stat('/tmp/world', (err, stats) => { It is important to correctly order the operations by awaiting the results of one before invoking the other: -```js esm +```mjs // Using ESM syntax import { rename, stat } from 'fs/promises'; @@ -6161,7 +6161,7 @@ try { } ``` -```js cjs +```cjs // Using CommonJS syntax const { rename, stat } = require('fs/promises'); @@ -6179,7 +6179,7 @@ const { rename, stat } = require('fs/promises'); Or, when using the callback APIs, move the `fs.stat()` call into the callback of the `fs.rename()` operation: -```js esm +```mjs import { rename, stat } from 'fs'; rename('/tmp/hello', '/tmp/world', (err) => { @@ -6191,7 +6191,7 @@ rename('/tmp/hello', '/tmp/world', (err) => { }); ``` -```js cjs +```cjs const { rename, stat } = require('fs/promises'); rename('/tmp/hello', '/tmp/world', (err) => { @@ -6216,7 +6216,7 @@ to the current working directory as determined by calling `process.cwd()`. Example using an absolute path on POSIX: -```js esm +```mjs import { open } from 'fs/promises'; let fd; @@ -6230,7 +6230,7 @@ try { Example using a relative path on POSIX (relative to `process.cwd()`): -```js esm +```mjs import { open } from 'fs/promises'; let fd; @@ -6249,7 +6249,7 @@ added: v7.6.0 For most `fs` module functions, the `path` or `filename` argument may be passed as a {URL} object using the `file:` protocol. -```js esm +```mjs import { readFileSync } from 'fs'; readFileSync(new URL('file:///tmp/hello')); @@ -6263,7 +6263,7 @@ On Windows, `file:` {URL}s with a host name convert to UNC paths, while `file:` {URL}s with drive letters convert to local absolute paths. `file:` {URL}s without a host name nor a drive letter will result in an error: -```js esm +```mjs import { readFileSync } from 'fs'; // On Windows : @@ -6287,7 +6287,7 @@ the drive letter. Using another separator will result in an error. On all other platforms, `file:` {URL}s with a host name are unsupported and will result in an error: -```js esm +```mjs import { readFileSync } from 'fs'; // On other platforms: @@ -6304,7 +6304,7 @@ readFileSync(new URL('file:///tmp/hello')); A `file:` {URL} having encoded slash characters will result in an error on all platforms: -```js esm +```mjs import { readFileSync } from 'fs'; // On Windows @@ -6322,7 +6322,7 @@ readFileSync(new URL('file:///p/a/t/h/%2f')); On Windows, `file:` {URL}s having encoded backslash will result in an error: -```js esm +```mjs import { readFileSync } from 'fs'; // On Windows @@ -6342,7 +6342,7 @@ be relative or absolute: Example using an absolute path on POSIX: -```js esm +```mjs import { open } from 'fs/promises'; let fd; @@ -6382,7 +6382,7 @@ at any given time so it is critical to close the descriptor when operations are completed. Failure to do so will result in a memory leak that will eventually cause an application to crash. -```js esm +```mjs import { open, close, fstat } from 'fs'; function closeFd(fd) { @@ -6416,7 +6416,7 @@ file descriptor. These objects are better managed by the system to ensure that resources are not leaked. However, it is still required that they are closed when operations are completed: -```js esm +```mjs import { open } from 'fs/promises'; let file;