Close remaining File API spec gaps in FileReader (#57745)

Summary:
Pull Request resolved: https://github.com/react/react-native/pull/57745

Builds on [#57692](https://github.com/facebook/react-native/pull/57692), which fixed the `abort()` state machine and reset `result`/`error` at the start of each read via the `_startRead()` helper. A few gaps remain versus the [File API spec](https://w3c.github.io/FileAPI/): a read that starts while the reader is `LOADING` is silently superseded instead of throwing, `loadstart` is never dispatched, and `error` is a plain `Error` rather than a `DOMException`.

This change:

- throws an `InvalidStateError` `DOMException` when a read starts while the reader is `LOADING`, by extending the `_startRead()` helper
- fires `loadstart` when a read begins
- exposes `error` as a `DOMException` (`NotReadableError`), matching the spec typing

No `progress` event is synthesized: `NativeFileReaderModule` resolves the whole payload in a single promise, so there is no incremental read to observe. The spec fires `progress` opportunistically as bytes stream in (it is not a required event), and emitting one post-completion `progress` with `loaded === total` would report data the reader never actually measured — a handler would also see `reader.result === null` at that point. The lifecycle is covered by `loadstart`/`load`/`error`/`abort`/`loadend`. The legacy `readystatechange` event is left untouched, and the deprecated `readAsBinaryString()` is out of scope.

## Changelog:

[GENERAL] [FIXED] - Fire `loadstart`, throw `InvalidStateError` on overlapping reads, and expose `FileReader.error` as a `DOMException`.

Reviewed By: christophpurrer

Differential Revision: D113819663

fbshipit-source-id: c7c37b3b578d825cdccf73840b2c0742b6a4eaf9
This commit is contained in:
Peter Abbondanzo authored and meta-codesync[bot] committed 2026-07-28 22:52:01 -07:00
1 parent ca750feefb
commit 544141efab
2 files changed
+163 -11

No files matched your search

+29 -10
View File
@@ -17,6 +17,7 @@ import {
setEventHandlerAttribute,
} from '../../src/private/webapis/dom/events/EventHandlerAttributes';
import EventTarget from '../../src/private/webapis/dom/events/EventTarget';
import DOMException from '../../src/private/webapis/errors/DOMException';
import NativeFileReaderModule from './NativeFileReaderModule';
import {toByteArray} from 'base64-js';
@@ -41,7 +42,7 @@ class FileReader extends EventTarget {
DONE: number = DONE;
_readyState: ReadyState;
_error: ?Error;
_error: ?DOMException;
_result: ?ReaderResult;
_aborted: boolean = false;
_readId: number = 0;
@@ -57,7 +58,13 @@ class FileReader extends EventTarget {
this._result = null;
}
_startRead(): number {
_startRead(methodName: string): number {
if (this._readyState === LOADING) {
throw new DOMException(
`Failed to execute '${methodName}' on 'FileReader': The object is already busy reading Blobs.`,
'InvalidStateError',
);
}
this._aborted = false;
this._error = null;
this._result = null;
@@ -69,7 +76,9 @@ class FileReader extends EventTarget {
_setReadyState(newState: ReadyState) {
this._readyState = newState;
this.dispatchEvent(new Event('readystatechange'));
if (newState === DONE) {
if (newState === LOADING) {
this.dispatchEvent(new Event('loadstart'));
} else if (newState === DONE) {
if (this._aborted) {
this.dispatchEvent(new Event('abort'));
} else if (this._error) {
@@ -83,6 +92,16 @@ class FileReader extends EventTarget {
}
}
_toDOMException(error: unknown): DOMException {
if (error instanceof DOMException) {
return error;
}
if (error instanceof Error) {
return new DOMException(error.message, 'NotReadableError');
}
return new DOMException(String(error), 'NotReadableError');
}
readAsArrayBuffer(blob: ?Blob): void {
if (blob == null) {
throw new TypeError(
@@ -90,7 +109,7 @@ class FileReader extends EventTarget {
);
}
const readId = this._startRead();
const readId = this._startRead('readAsArrayBuffer');
NativeFileReaderModule.readAsDataURL(blob.data).then(
(text: string) => {
@@ -108,7 +127,7 @@ class FileReader extends EventTarget {
if (readId !== this._readId) {
return;
}
this._error = error;
this._error = this._toDOMException(error);
this._setReadyState(DONE);
},
);
@@ -121,7 +140,7 @@ class FileReader extends EventTarget {
);
}
const readId = this._startRead();
const readId = this._startRead('readAsDataURL');
NativeFileReaderModule.readAsDataURL(blob.data).then(
(text: string) => {
@@ -135,7 +154,7 @@ class FileReader extends EventTarget {
if (readId !== this._readId) {
return;
}
this._error = error;
this._error = this._toDOMException(error);
this._setReadyState(DONE);
},
);
@@ -148,7 +167,7 @@ class FileReader extends EventTarget {
);
}
const readId = this._startRead();
const readId = this._startRead('readAsText');
NativeFileReaderModule.readAsText(blob.data, encoding).then(
(text: string) => {
@@ -162,7 +181,7 @@ class FileReader extends EventTarget {
if (readId !== this._readId) {
return;
}
this._error = error;
this._error = this._toDOMException(error);
this._setReadyState(DONE);
},
);
@@ -181,7 +200,7 @@ class FileReader extends EventTarget {
return this._readyState;
}
get error(): ?Error {
get error(): ?DOMException {
return this._error;
}
@@ -12,6 +12,9 @@
import type Event from '../../../src/private/webapis/dom/events/Event';
import DOMException from '../../../src/private/webapis/errors/DOMException';
const FileReaderModuleMock = require('../__mocks__/FileReaderModule').default;
const Blob = require('../Blob').default;
const FileReader = require('../FileReader').default;
const NativeFileReaderModule = require('../NativeFileReaderModule').default;
@@ -25,6 +28,10 @@ jest.mock('../../BatchedBridge/NativeModules', () => ({
}));
describe('FileReader', function () {
afterEach(() => {
jest.restoreAllMocks();
});
it('should read blob as text', async () => {
const e = await new Promise<Event>((resolve, reject) => {
const reader = new FileReader();
@@ -119,7 +126,8 @@ describe('FileReader', function () {
expect(reader.result).toBe(null);
expect(reader.error).toBe(null);
await failedRead;
expect(reader.error).toBe(error);
expect(reader.error).toBeInstanceOf(DOMException);
expect(reader.error?.message).toBe(error.message);
readAsText.mockReturnValueOnce(new Promise(() => {}));
reader.readAsText(new Blob());
@@ -142,4 +150,129 @@ describe('FileReader', function () {
// $FlowFixMe[cannot-resolve-name]
expect(new TextDecoder().decode(ab)).toBe('42');
});
it('fires lifecycle events in spec order for a successful read', async () => {
const reader = new FileReader();
const events: Array<string> = [];
const done = new Promise<void>(resolve => {
for (const type of ['loadstart', 'load', 'loadend']) {
reader.addEventListener(type, () => {
events.push(type);
if (type === 'loadend') {
resolve();
}
});
}
reader.readAsText(new Blob());
});
await done;
expect(events).toEqual(['loadstart', 'load', 'loadend']);
});
it('fires loadstart with the reader in the LOADING state', async () => {
const reader = new FileReader();
let stateAtLoadStart: ?number = null;
const done = new Promise<Event>(resolve => {
reader.onloadstart = () => {
stateAtLoadStart = reader.readyState;
};
reader.onload = resolve;
reader.readAsText(new Blob());
});
await done;
expect(stateAtLoadStart).toBe(FileReader.LOADING);
});
it('does not dispatch a progress event (native reads are atomic)', async () => {
const reader = new FileReader();
let progressed = false;
const done = new Promise<Event>((resolve, reject) => {
reader.onprogress = () => {
progressed = true;
};
reader.onload = resolve;
reader.onerror = reject;
reader.readAsText(new Blob());
});
await done;
expect(progressed).toBe(false);
});
it('dispatches readystatechange for EMPTY -> LOADING -> DONE', async () => {
const reader = new FileReader();
const states: Array<number> = [];
const done = new Promise<Event>(resolve => {
reader.addEventListener('readystatechange', () => {
states.push(reader.readyState);
});
reader.onload = resolve;
reader.readAsText(new Blob());
});
await done;
expect(states).toEqual([FileReader.LOADING, FileReader.DONE]);
});
it('fires error and loadend (not load) when the native read rejects', async () => {
jest
.spyOn(FileReaderModuleMock, 'readAsText')
.mockRejectedValueOnce(new Error('read failed'));
const reader = new FileReader();
let loaded = false;
let errored = false;
const done = new Promise<Event>(resolve => {
reader.onload = () => {
loaded = true;
};
reader.onerror = () => {
errored = true;
};
reader.onloadend = resolve;
reader.readAsText(new Blob());
});
await done;
expect(errored).toBe(true);
expect(loaded).toBe(false);
expect(reader.readyState).toBe(FileReader.DONE);
expect(reader.result).toBe(null);
});
it('exposes a read failure as a DOMException', async () => {
jest
.spyOn(FileReaderModuleMock, 'readAsText')
.mockRejectedValueOnce(new Error('read failed'));
const reader = new FileReader();
await new Promise<Event>(resolve => {
reader.onloadend = resolve;
reader.readAsText(new Blob());
});
expect(reader.error).toBeInstanceOf(DOMException);
expect(reader.error?.name).toBe('NotReadableError');
});
it('throws InvalidStateError when a read starts while LOADING', () => {
const reader = new FileReader();
reader.readAsText(new Blob());
expect(reader.readyState).toBe(FileReader.LOADING);
let thrown: unknown = null;
try {
reader.readAsText(new Blob());
} catch (e) {
thrown = e;
}
expect(thrown).toBeInstanceOf(DOMException);
if (thrown instanceof DOMException) {
expect(thrown.name).toBe('InvalidStateError');
}
// The in-flight read is untouched.
expect(reader.readyState).toBe(FileReader.LOADING);
});
it('throws a TypeError when the blob is null', () => {
const reader = new FileReader();
expect(() => reader.readAsText(null)).toThrow(TypeError);
expect(reader.readyState).toBe(FileReader.EMPTY);
});
});