Node.js Reference ยท Buffers and Encoding
The Node.js File class
Reference for the Node.js File class from node:buffer: a Blob with a name and a modified time, how to construct it, read it, slice it and how it differs from Blob.
File is a Blob with two extra properties: a name and a lastModified time. It follows the web platform API of the same name, so code written for the browser can run in Node.js. It is available as a global and can also be imported from node:buffer.
A File does not touch the file system. Despite the name it is an immutable, in-memory (or lazily read) chunk of bytes plus metadata, useful for building FormData bodies, passing data between APIs that expect the web File shape and testing upload code. To read a real file from disk as a Blob, use fs.openAsBlob(path), which returns a Blob.
const file = new File(["hello"], "greeting.txt", { type: "text/plain" }); file.name; // "greeting.txt" file.size; // 5
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
import { File } from "node:buffer"; new File(fileBits, fileName, options) // fileBits: Array of string | ArrayBuffer | TypedArray | DataView | Blob | File // options: { type?: string, lastModified?: number, endings?: "transparent" | "native" }
| Name | Description |
|---|---|
fileBits |
An array of parts that are concatenated, in order, to make the content. |
fileName |
The name of the file. Required. It is converted to a string and not validated or split on slashes. |
options.type |
MIME type. Lowercased; a string with characters outside printable ASCII becomes "". Default "". |
options.lastModified |
Milliseconds since the Unix epoch. Default: the current time. |
options.endings |
Line-ending handling for string parts: "transparent" (default) keeps them, "native" converts \n to the platform's ending. |
Properties: name, lastModified, and the inherited size and type.
Methods (from Blob): text(), arrayBuffer(), bytes(), stream() and slice(start, end, type). All reading methods return promises.
Errors and edge cases:
- Fewer than two arguments throws
ERR_MISSING_ARGS. - A
fileBitsthat is not an array (for example a plain string) throwsERR_INVALID_ARG_TYPE. Elements of other types are converted to strings, so{}becomes"[object Object]". slice()returns aBlob, not aFile, so the name and modified time are not carried over.JSON.stringify(file)gives{}; the properties are on the prototype and the content is not serializable.
Usage notes
- Immutable: the content is copied at construction (for strings and buffers). Changing an
Uint8Arrayafterwards does not change the file. - Uses in Node.js: appending to
FormData(form.append("upload", file)), passing tofetch()bodies and APIs such asResponseorURL.createObjectURL().fetch()with aFormDatacontaining aFilesends the name in theContent-Dispositionheader. Blobfor anonymous data: useBlobwhen no name makes sense; useFilewhen the receiver expectsname. AFileis also accepted anywhere aBlobis.- Memory: each reading method makes its own copy. Prefer
stream()for large content to avoid holding everything at once. - Browser-like but not identical: there is no
webkitRelativePath, andFileobjects cannot come from user selection since there is no file picker. - Cloning: a
Filecan be passed throughstructuredClone()andpostMessage()to worker threads on current Node.js versions; test it on your version before relying on it. - Stability:
Filehas been global since Node.js 20.
Related
Buffer,Blob,Buffer.from(),ArrayBufferin Node- Lessons: Buffers