Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 1,000,000+ packages pre-installed, including generic-filehandle with all npm packages installed. Try it out:

var genericFilehandle = require("generic-filehandle")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

generic-filehandle v2.0.3

uniform interface for accessing binary data from local files, remote HTTP resources, and browser Blob data


NPM version Build Status codecov

Provides a uniform interface for accessing binary data from local files, remote HTTP resources, and Blob data in the browser. Implements a subset of the Node.js v10 promise-based FileHandle API.


    import {LocalFile,RemoteFile,BlobFile} from 'generic-filehandle'

    // operate on a local file path
    const local = new LocalFile('/some/file/path/file.txt')

    // operate on a remote file path
    const remote = new RemoteFile('')

    // operate on blob objects
    const blobfile = new BlobFile(new Blob([some_existing_buffer], { type: "text/plain" }))

    // read slice of file, works on remote files with range request, pre-allocate buffer
    const buf = Buffer.alloc(10)
    const {bytesRead} = await, 0, 10, 10)

    // readFile, returns buffer
    const buf = remote.readFile()

Important: under node.js, you should supply a fetch function to the RemoteFile constructor

    import {RemoteFile} from 'generic-filehandle'
    import fetch from 'node-fetch'
    const remote = new RemoteFile('', {fetch})


async read(buf:Buffer, offset: number=0, length: number, position: number=0, opts?: Options): Promise<{bytesRead:number,buffer:Buffer}>

  • buf - a pre-allocated buffer that can contain length bytes
  • offset - an offset into the buffer to write into
  • length - a length of data to read
  • position - the byte offset in the file to read from
  • opts - optional Options object

Returns a Promise for the number of bytes read, and the data will be copied into the Buffer provided in the arguments.

async readFile(opts?: Options): Promise<Buffer | string>

Returns a Promise for a buffer or string containing the contents of the whole file.

async stat() : Promise<{size: number}>

Returns a Promise for an object containing as much information about the file as is available. At minimum, the size of the file will be present.


The Options object for the constructor, read and readFile can contain abort signal to customize behavior. All entries are optional.

  • signal <AbortSignal> - an AbortSignal that is passed to remote file fetch() API or other file readers
  • headers <Object <string, string> >- extra HTTP headers to pass to remote file fetch() API
  • overrides <Object> - extra parameters to pass to the remote file fetch() API
  • fetch <Function> - a custom fetch callback, otherwise defaults to the environment (initialized in constructor)
  • encoding <string> - if specified, then this function returns a string. Otherwise it returns a buffer. Currently only utf8 encoding is supported.

The Options object for readFile can also contain an entry encoding. The default is no encoding, in which case the file contents are returned as a buffer. Currently, the only available encoding is utf8, and specifying that will cause the file contents to be returned as a string. For compatibility with the Node API, the readFile method will accept the string "utf8" instead of an Options object.


This library implements a subset of the Node.js v10 promise-based FileHandle API.


RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free