Class FileHandle

constructor

• new FileHandle(fdOrFile): FileHandle

• Parameters

  • fdOrFile: number | File<FileSystem>

  Returns FileHandle

Readonlyfd

Readonly Internalfile

[asyncDispose]

• [asyncDispose](): Promise<void>

• Returns Promise<void>

appendFile

• appendFile(data, _options?): Promise<void>

• Asynchronously append data to a file, creating the file if it does not exist. The underlying file will not be closed automatically. The FileHandle must have been opened for appending.

  Parameters

  • data: string | Uint8Array

    The data to write. If something other than a Buffer or Uint8Array is provided, the value is coerced to a string.
  • _options: BufferEncoding | ObjectEncodingOptions & FlagAndOpenMode = {}

    Either the encoding for the file, or an object optionally specifying the encoding, file mode, and flag.

    • encoding defaults to 'utf8'.
    • mode defaults to 0o666.
    • flag defaults to 'a'.

  Returns Promise<void>

chmod

• chmod(mode): Promise<void>

• Asynchronous fchmod(2) - Change permissions of a file.

  Parameters

  • mode: Mode

    A file mode. If a string is passed, it is parsed as an octal integer.

  Returns Promise<void>

chown

• chown(uid, gid): Promise<void>

• Asynchronous fchown(2) - Change ownership of a file.

  Parameters

  • uid: number
  • gid: number

  Returns Promise<void>

close

• close(): Promise<void>

• Asynchronous close(2) - close a FileHandle.

  Returns Promise<void>

createReadStream

• createReadStream(options?): ReadStream

• Creates a stream for reading from the file.

  Parameters

  • Optionaloptions: CreateReadStreamOptions

    Options for the readable stream

  Returns ReadStream

createWriteStream

• createWriteStream(options?): WriteStream

• Creates a stream for writing to the file.

  Parameters

  • Optionaloptions: CreateWriteStreamOptions

    Options for the writeable stream.

  Returns WriteStream

datasync

• datasync(): Promise<void>

• Asynchronous fdatasync(2) - synchronize a file's in-core state with storage device.

  Returns Promise<void>

read

• read<TBuffer>(buffer, offset?, length?, position?): Promise<FileReadResult<TBuffer>>

• Asynchronously reads data from the file. The FileHandle must have been opened for reading.

  Type Parameters

  • TBuffer extends ArrayBufferView

  Parameters

  • buffer: TBuffer

    The buffer that the data will be written to.
  • Optionaloffset: number

    The offset in the buffer at which to start writing.
  • Optionallength: number

    The number of bytes to read.
  • Optionalposition: null | number

    The offset from the beginning of the file from which data should be read. If null, data will be read from the current position.

  Returns Promise<FileReadResult<TBuffer>>

readableWebStream

• readableWebStream(options?): ReadableStream<Uint8Array>
• Experimental

  Returns a ReadableStream that may be used to read the files data.

  An error will be thrown if this method is called more than once or is called after the FileHandle is closed or closing.

  While the ReadableStream will read the file to completion, it will not close the FileHandle automatically. User code must still call the fileHandle.close() method.

  Parameters

  • options: ReadableWebStreamOptions = {}

  Returns ReadableStream<Uint8Array>

  Since

  v17.0.0

readFile

• readFile(_options?): Promise<Buffer>

• Asynchronously reads the entire contents of a file. The underlying file will not be closed automatically. The FileHandle must have been opened for reading.

  Parameters

  • Optional_options: {
        flag?: OpenMode;
    }

    An object that may contain an optional flag. If a flag is not provided, it defaults to 'r'.

    • Optionalflag?: OpenMode

  Returns Promise<Buffer>
• readFile(_options): Promise<string>

• Asynchronously reads the entire contents of a file.

  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.readFile() 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.

  Parameters

  • _options: BufferEncoding | ObjectEncodingOptions & FlagAndOpenMode

  Returns Promise<string>

  Fulfills upon a successful read with the contents of the file. If no encoding is specified (using options.encoding), the data is returned as a {Buffer} object. Otherwise, the data will be a string.

  Since

  v10.0.0

readLines

• readLines(options?): Interface

• Parameters

  • Optionaloptions: CreateReadStreamOptions

  Returns Interface

  Todo

  Implement

readv

• readv(buffers, position?): Promise<ReadVResult>

• Asynchronous readv. Reads into multiple buffers.

  Parameters

  • buffers: ArrayBufferView[]

    An array of Uint8Array buffers.
  • Optionalposition: number

    The position in the file where to begin reading.

  Returns Promise<ReadVResult>

  The number of bytes read.

stat

• stat(opts): Promise<BigIntStats>

• Asynchronous fstat(2) - Get file status.

  Parameters

  • opts: BigIntOptions

  Returns Promise<BigIntStats>
• stat(opts?): Promise<Stats>

• Parameters

  • Optionalopts: StatOptions & {
        bigint?: false;
    }

  Returns Promise<Stats>

  Fulfills with an {fs.Stats} for the file.

  Since

  v10.0.0

sync

• sync(): Promise<void>

• Asynchronous fsync(2) - synchronize a file's in-core state with the underlying storage device.

  Returns Promise<void>

truncate

• truncate(length?): Promise<void>

• Asynchronous ftruncate(2) - Truncate a file to a specified length.

  Parameters

  • Optionallength: null | number

    If not specified, defaults to 0.

  Returns Promise<void>

utimes

• utimes(atime, mtime): Promise<void>

• Asynchronously change file timestamps of the file.

  Parameters

  • atime: string | number | Date

    The last access time. If a string is provided, it will be coerced to number.
  • mtime: string | number | Date

    The last modified time. If a string is provided, it will be coerced to number.

  Returns Promise<void>

write

• write(data, posOrOff?, lenOrEnc?, position?): Promise<{
      buffer: FileContents;
      bytesWritten: number;
  }>

• Asynchronously writes string to the file. The FileHandle must have been opened for writing. It is unsafe to call write() multiple times on the same file without waiting for the Promise to be resolved (or rejected). For this scenario, fs.createWriteStream is strongly recommended.

  Parameters

  • data: FileContents
  • OptionalposOrOff: null | number
  • OptionallenOrEnc: number | BufferEncoding
  • Optionalposition: null | number

  Returns Promise<{
      buffer: FileContents;
      bytesWritten: number;
  }>
• write<TBuffer>(buffer, offset?, length?, position?): Promise<{
      buffer: TBuffer;
      bytesWritten: number;
  }>

• Write buffer to the file.

  The promise is fulfilled with an object containing two properties:

  It is unsafe to use filehandle.write() multiple times on the same file without waiting for the promise to be fulfilled (or rejected). For this scenario, use filehandle.createWriteStream().

  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.

  Type Parameters

  • TBuffer extends Uint8Array

  Parameters

  • buffer: TBuffer
  • Optionaloffset: number

    The start position from within buffer where the data to write begins.
  • Optionallength: number

    The number of bytes from buffer to write.
  • Optionalposition: number

    The offset from the beginning of the file where the data from buffer should be written. If position is not a number, the data will be written at the current position. See the POSIX pwrite(2) documentation for more detail.

  Returns Promise<{
      buffer: TBuffer;
      bytesWritten: number;
  }>

  Since

  v10.0.0

• write(data, position?, encoding?): Promise<{
      buffer: string;
      bytesWritten: number;
  }>

• Write buffer to the file.

  The promise is fulfilled with an object containing two properties:

  It is unsafe to use filehandle.write() multiple times on the same file without waiting for the promise to be fulfilled (or rejected). For this scenario, use filehandle.createWriteStream().

  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.

  Parameters

  • data: string
  • Optionalposition: number

    The offset from the beginning of the file where the data from buffer should be written. If position is not a number, the data will be written at the current position. See the POSIX pwrite(2) documentation for more detail.
  • Optionalencoding: BufferEncoding

  Returns Promise<{
      buffer: string;
      bytesWritten: number;
  }>

  Since

  v10.0.0

writeFile

• writeFile(data, _options?): Promise<void>

• Asynchronously writes data to a file, replacing the file if it already exists. The underlying file will not be closed automatically. The FileHandle must have been opened for writing. It is unsafe to call writeFile() multiple times on the same file without waiting for the Promise to be resolved (or rejected).

  Parameters

  • data: string | Uint8Array

    The data to write. If something other than a Buffer or Uint8Array is provided, the value is coerced to a string.
  • _options: WriteFileOptions = {}

    Either the encoding for the file, or an object optionally specifying the encoding, file mode, and flag.

    • encoding defaults to 'utf8'.
    • mode defaults to 0o666.
    • flag defaults to 'w'.

  Returns Promise<void>

writev

• writev(buffers, position?): Promise<WriteVResult>

• Asynchronous writev. Writes from multiple buffers.

  Parameters

  • buffers: Uint8Array[]

    An array of Uint8Array buffers.
  • Optionalposition: number

    The position in the file where to begin writing.

  Returns Promise<WriteVResult>

  The number of bytes written.