diff --git a/doc/api/fs.md b/doc/api/fs.md index e11c057802e763..fceb333f5d0935 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -332,6 +332,33 @@ If one or more `filehandle.read()` calls are made on a file handle and then a position till the end of the file. It doesn't always read from the beginning of the file. +#### `filehandle.readJSON(options)` + + +* `options` {Object|string} + * `encoding` {string|null} **Default:** `'utf8'` + * `reviver` {Function} Reviver function passed to [`JSON.parse`][]. + * `signal` {AbortSignal} allows aborting an in-progress readJSON +* Returns: {Promise} Fulfills upon a successful read with the contents of the + file parsed with [`JSON.parse`][]. + +Asynchronously reads the contents of a file and call [`JSON.parse`][] on it. + +The `encoding` and `signal` options are passed to the underlying +[`fsPromises.readFile()`][] call and the `reviver` option is passed to +[`JSON.parse`][]. + +If `options` is a string, then it specifies the `encoding`. + +The {FileHandle} has to support reading. + +If one or more `filehandle.read()` calls are made on a file handle and then a +`filehandle.readJSON()` call is made, the data will be read from the current +position till the end of the file. It doesn't always read from the beginning +of the file. + #### `filehandle.readv(buffers[, position])` + +* `path` {string|Buffer|URL|FileHandle} filename or `FileHandle` +* `options` {Object|string} + * `encoding` {string|null} **Default:** `'utf8'` + * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`. + * `reviver` {Function} Reviver function passed to [`JSON.parse`][]. + * `signal` {AbortSignal} allows aborting an in-progress readFile +* Returns: {Promise} Fulfills with the contents of the file parsed with + [`JSON.parse`][]. + +Asynchronously reads the contents of a file and call [`JSON.parse`][] on it. + +The `path` parameter, and the `encoding`, `flag` and `signal` options are passed +to the underlying [`fsPromises.readFile()`][] call and the `reviver` option is +passed to [`JSON.parse`][]. + +If `options` is a string, then it specifies the encoding. + +It is possible to abort an ongoing `readJSON` using an {AbortSignal}. If a +request is aborted the promise returned is rejected with an `AbortError`. + +Any specified {FileHandle} has to support reading. + +```mjs +import { readJSON } from 'fs/promises'; + +const json = await readJSON('package.json'); +``` + ### `fsPromises.readlink(path[, options])` + +* `path` {string|Buffer|URL|integer} filename or file descriptor +* `options` {Object|string} + * `encoding` {string|null} **Default:** `'utf8'` + * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`. + * `reviver` {Function} Reviver function passed to [`JSON.parse`][]. + * `signal` {AbortSignal} allows aborting an in-progress readJSON +* `callback` {Function} + * `err` {Error|AggregateError} + * `data` {any} + +Asynchronously reads the contents of a file and call [`JSON.parse`][] on it. + +The `path` parameter, and the `encoding`, `flag` and `signal` options are passed +to the underlying [`fs.readFileSync()`][] call and the `reviver` option is +passed to to [`JSON.parse`][]. + +For detailed information, see the documentation of [`fs.readFile()`][]. + +```mjs +import { readJSON } from 'fs'; + +readJSON('package.json', callback); +``` + ### `fs.readlink(path[, options], callback)` + +* `path` {string|Buffer|URL|integer} filename or file descriptor +* `options` {Object|string} + * `encoding` {string|null} **Default:** `'utf8'` + * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`. + * `reviver` {Function} Reviver function passed to [`JSON.parse`][]. +* Returns: {any} + +Reads the contents of the `path` and returns the result of calling +[`JSON.parse`][] on it. + +The `path` parameter, and the `encoding` and `flag` options are passed to the +underlying [`fs.readFileSync()`][] call and the `reviver` option is passed to +to [`JSON.parse`][]. + +For detailed information, see the documentation of [`fs.readFile()`][]. + +```mjs +import { readJSONSync } from 'fs'; + +const json = readJSONSync('package.json'); +``` + ### `fs.readlinkSync(path[, options])`