generic-filehandle

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.

Usage

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('http://somesite.com/file.txt')

// 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 remote.read(buf, 0, 10, 10)
console.log(buf.toString())

// 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('http://somesite.com/file.txt', { fetch })

API

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.

async close() : Promise<void>

Closes the filehandle.

Options

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.

References

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

3.2.0 (2024-06-21)

3.1.2 (2024-3-4)

• Fix response.buffer deprecation warning (always use response.arrayBuffer and Buffer.from)

3.1.1 (2023-09-09)

• Use bind to make sure fetch has the right scope

3.1.0 (2023-08-28)

• Look for fetch in globalThis

3.0.1 (2022-12-17)

• Fix sourceMap

3.0.0 (2022-07-18)

• Remove the utility that converts a RemoteFile into a LocalFile when a file:/// is passed in

2.2.3 (2022-05-19)

Features

• explicit buffer import (#102) (a9223d6)

• Explicitly import Buffer to try to help deployment on some bundlers

2.2.2 (2021-12-14)

• Add esm module build with less babelification for smaller bundle size

2.2.1 (2021-10-03)

• Make this.url a protected instead of private field

2.2.0 (2021-09-22)

Features

• resolve empty for node-specific modules in browser context (#88) (044ab0f)

• Use "browser" field of package.json to hide localFile import of 'fs' instead of hiding behind webpack flag. Thanks to @manzt for contributing! (#88)

2.1.0 (2021-03-10)

• Refetch with cache:'reload' header on CORS error to bypass Chrome cache pollution

2.0.3 (2020-06-05)

• Fix ability to supply things like Authorization token to the constructor

example syntax

const f = new RemoteFile("http://yourwebsite/file.bam", {
  overrides: {
    headers: {
      Authorization: "Basic YWxhZGRpbjpvcGVuc2VzYW1l",
    },
  },
});

2.0.2 (2020-04-07)

• Upgrade dependencies

2.0.1 (2019-10-25)

• Fix the typescript typings for stat and some other things

2.0.0 (2019-06-05)

• Update to use Node.js return type e.g. {buffer,bytesRead} instead of just bytesRead

1.0.9 (2019-05-01)

• Add ability to read a fetch response's Body().buffer() instead of Body.arrayBuffer() that is normally returned
• Fix issue with using un-polyfilled fetch

1.0.8 (2019-04-17)

• Properly added typescript type declaration files to the distribution

1.0.7 (2019-04-16)

• Remove polyfill of fetch, now uses "globalThis" fetch or supply opts.fetch to the constructor of RemoteFile (@rbuels, pull #8)
• Translates file:// URL to LocalFile in the implementation (@rbuels, pull #7)
• Allow adding fetch overrides to the constructor of RemoteFile
• Make LocalFile lazily evaluate opening the file until usage

1.0.6 (2019-04-15)

• Added documentation about the Options object
• Added encoding option to the Options for readFile which can return text if specified as utf8 or you can also directly call filehandle.readFile('utf8')

1.0.5 (2019-04-12)

• Added BlobFile class, implementation (thanks @garrettjstevens!)

1.0.4 (2019-04-11)

• Add @types/node for typescript

1.0.3 (2019-04-11)

• Downgrade quick-lru for node 6

1.0.2 (2019-04-10)

• Fix usage of fetch headers
• Add overrides parameter to options

1.0.1 (2019-04-10)

• Fix some typescript definitions

1.0.0

• Initial implementation of a filehandle object with local and remote support