lazy-file

lazy-file is a lazy, streaming File implementation for JavaScript. It allows you to easily create File objects that defer reading their contents until needed, which is ideal for situations where a file's contents do not fit in memory all at once.

The Problem

JavaScript's File API is useful, but it's not a great fit for streaming server environments where you don't want to buffer file contents. In particular, the File constructor requires the contents of a file to be supplied up front when the object is first created.

A LazyFile improves this model by accepting a LazyFileContent in its constructor. All other File functionality work exactly the same as the original, including instanceof File.

Installation

Install from npm:

npm install @mjackson/lazy-file

Usage

import { type LazyFileContent, LazyFile } from "@mjackson/lazy-file";

let content: LazyFileContent = {
  // The total length of this file in bytes.
  byteLength: 100,
  // A "reader" function that provides a stream of data for the file contents,
  // beginning at the `start` index and ending at `end`.
  read(start, end) {
    // ... read the file contents from somewhere and return a ReadableStream
    return new ReadableStream({
      start(controller) {
        controller.enqueue("X".repeat(100).slice(start, end));
        controller.close();
      }
    });
  }
};

let file = new LazyFile(content, "example.txt", { type: "text/plain" });
await file.arrayBuffer(); // ArrayBuffer of the file's content
file.name; // "example.txt"
file.type; // "text/plain"

License

See LICENSE