Class FileHandle

constructor

• new FileHandle(fdOrFile): FileHandle

• Parameters

  • fdOrFile: number | File

  Returns FileHandle

Readonly fd

Readonly Internal file

[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. If encoding is not supplied, the default of 'utf8' is used. If mode is not supplied, the default of 0o666 is used. If mode is a string, it is parsed as an octal integer. If flag is not supplied, the default of 'a' is used.

  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 ReadStream for reading from the file.

  Parameters

  • Optional options: CreateReadStreamOptions

    Options for the readable stream

  Returns ReadStream

  A ReadStream object.

createWriteStream

• createWriteStream(options?): WriteStream

• Creates a WriteStream for writing to the file.

  Parameters

  • Optional options: CreateWriteStreamOptions

    Options for the writeable stream.

  Returns WriteStream

  A WriteStream object

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.
  • Optional offset: number

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

    The number of bytes to read.
  • Optional position: 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>>

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'.

    • Optional flag?: OpenMode

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

• Parameters

  • _options: BufferEncoding | ObjectEncodingOptions & FlagAndOpenMode

  Returns Promise<string>

readLines

• readLines(options?): Interface

• Parameters

  • Optional options: CreateReadStreamOptions

  Returns Interface

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

readv

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

• Asynchronous readv. Reads into multiple buffers.

  Parameters

  • buffers: ArrayBufferView[]

    An array of Uint8Array buffers.
  • Optional position: 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

  • Optional opts: StatOptions & {
        bigint?: false;
    }

  Returns Promise<Stats>

sync

• sync(): Promise<void>

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

  Returns Promise<void>

truncate

• truncate(len?): Promise<void>

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

  Parameters

  • Optional len: 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
  • Optional posOrOff: null | number
  • Optional lenOrEnc: number | BufferEncoding
  • Optional position: null | number

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

• Type Parameters

  • TBuffer extends Uint8Array

  Parameters

  • buffer: TBuffer
  • Optional offset: number
  • Optional length: number
  • Optional position: number

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

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

• Parameters

  • data: string
  • Optional position: number
  • Optional encoding: BufferEncoding

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

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. If encoding is not supplied, the default of 'utf8' is used. If mode is not supplied, the default of 0o666 is used. If mode is a string, it is parsed as an octal integer. If flag is not supplied, the default of 'w' is used.

  Returns Promise<void>

writev

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

• Asynchronous writev. Writes from multiple buffers.

  Parameters

  • buffers: Uint8Array[]

    An array of Uint8Array buffers.
  • Optional position: number

    The position in the file where to begin writing.

  Returns Promise<WriteVResult>

  The number of bytes written.