From 0c0ca857fcf20d5374b54166f27af180083d28dd Mon Sep 17 00:00:00 2001 From: avivkeller Date: Wed, 11 Nov 2026 11:17:23 -0500 Subject: [PATCH] lib: add File API support --- doc/api/cli.md | 11 + doc/api/globals.md | 88 ++ doc/node-config-schema.json | 4 + doc/node.1 | 6 + eslint.config.mjs | 3 + lib/internal/blob.js | 28 +- .../bootstrap/web/exposed-window-or-worker.js | 9 + lib/internal/file.js | 1 + lib/internal/filereader.js | 754 ++++++++++++++++++ lib/internal/process/pre_execution.js | 10 + lib/internal/progress_event.js | 152 ++++ lib/internal/webidl.js | 21 + lib/internal/webworker.js | 6 + src/dataqueue/queue.cc | 30 +- src/node_options.cc | 5 + src/node_options.h | 1 + test/parallel/test-filereader-flag.js | 19 + test/parallel/test-filereader-sync-flag.js | 14 + test/parallel/test-filereader.js | 339 ++++++++ test/wpt/status/FileAPI.json | 10 + .../status/FileAPI/reading-data-section.json | 11 + test/wpt/status/workers.json | 7 +- test/wpt/test-fileapi.js | 20 + test/wpt/test-filereader.js | 9 + test/wpt/test-workers.js | 2 +- 25 files changed, 1540 insertions(+), 20 deletions(-) create mode 100644 lib/internal/filereader.js create mode 100644 lib/internal/progress_event.js create mode 100644 test/parallel/test-filereader-flag.js create mode 100644 test/parallel/test-filereader-sync-flag.js create mode 100644 test/parallel/test-filereader.js create mode 100644 test/wpt/status/FileAPI.json create mode 100644 test/wpt/status/FileAPI/reading-data-section.json create mode 100644 test/wpt/test-fileapi.js create mode 100644 test/wpt/test-filereader.js diff --git a/doc/api/cli.md b/doc/api/cli.md index 5afcc6edaa5b..329bed69deac 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -1470,6 +1470,15 @@ added: Enable exposition of [EventSource Web API][] on the global scope. +### `--experimental-fileapi` + + + +Enable exposition of the [File API][] globals `FileReader`, `FileReaderSync`, +and `ProgressEvent` on the global scope. + ### `--experimental-import-meta-resolve` + +> Stability: 1.1 - Active development. Enable this API with the +> [`--experimental-fileapi`][] CLI flag. + +An implementation of {FileReader} from the [File API][]. `readAsArrayBuffer()`, +`readAsBinaryString()`, `readAsText()`, and `readAsDataURL()` read a {Blob} +asynchronously and report the result through `loadstart`, `progress`, `load`, +`abort`, `error`, and `loadend` events. `readyState` is `FileReader.EMPTY` +(`0`), `FileReader.LOADING` (`1`), or `FileReader.DONE` (`2`). + +`readAsDataURL()` produces a base64 `data:` URL. When the blob's type is the +empty string, the URL has no media type (`data:;base64,...`). Chrome and +Firefox use `application/octet-stream` in that case. `#`, `?`, `%`, and +whitespace in a media type are percent-encoded so the result stays one URL. + +`readAsText()` follows {TextDecoder} for the chosen encoding, including its +ICU requirement. Labels that the Encoding Standard maps to the replacement +encoding, such as `'iso-2022-kr'`, decode to U+FFFD when the input is not +empty. + +```js +const reader = new FileReader(); +reader.addEventListener('load', () => { + console.log(reader.result); // Prints: hello +}); +reader.readAsText(new Blob(['hello'])); +``` + +## Class: `FileReaderSync` + + + +> Stability: 1.1 - Active development. Enable this API with the +> [`--experimental-fileapi`][] CLI flag. + +An implementation of {FileReaderSync} from the [File API][]. The File API +exposes it only in dedicated and shared workers. Node.js also exposes it on +the main thread and in [`node:worker_threads`][] when this flag is enabled. + +`readAsArrayBuffer()`, `readAsBinaryString()`, `readAsText()`, and +`readAsDataURL()` read a {Blob} synchronously. A file-backed blob that can +still be read, such as one returned by [`fs.openAsBlob()`][], throws a +`NotReadableError`: the blob reader does not finish synchronously. If the +file has been removed, the error is `NotFoundError`. + +```js +const text = new FileReaderSync().readAsText(new Blob(['hello'])); +console.log(text); // Prints: hello +``` + ## Class: `FormData` + +> Stability: 1.1 - Active development. Enable this API with the +> [`--experimental-fileapi`][] CLI flag. + +An implementation of {ProgressEvent} from the [XMLHttpRequest Standard][]. +`FileReader` +dispatches `ProgressEvent`s for `loadstart`, `progress`, `load`, `abort`, +`error`, and `loadend`. Those events do not bubble and are not cancelable. +`lengthComputable`, `loaded`, and `total` return the values they were +initialized to (`false`, `0`, and `0` when omitted). The File API's +"fire a progress event" algorithm does not set those three fields, so events +fired by `FileReader` leave them at the defaults. + +```js +const event = new ProgressEvent('progress', { + lengthComputable: true, + loaded: 50, + total: 100, +}); +console.log(event.loaded / event.total); // Prints: 0.5 +``` + ## `queueMicrotask(callback)`