[kazupon]

Closes #42

addFile(), updateFile() and deleteFile() now return a promise that resolves when later preview requests see the change.

Breaking change

Up to 0.4.x, the three methods returned void and only posted messages to the Workers. They now return Promise<void>:

• They reject when called before ready() resolves to true, or after it fails. Such calls used to be dropped, or to reach only the Web Worker while ready() was in progress.
• They reject after dispose(). feat(vrowzer): dispose a runtime instance asynchronously #60 made them throw after dispose(), but that has not been released.
• Callers that ignore the returned promise see failures as unhandled rejections. The playground and the vite-plugin IDE now log them.

When the promise settles

• Each operation gets an id (crypto.randomUUID()). The Web Worker and the Service Worker answer with a new V_FS_ACK message, and the promise resolves when both have answered.
• The Service Worker answers right after writing its virtual filesystem, which is synchronous.
• The Web Worker answers after the dev server has processed the file change up to module graph invalidation: the plugins' watchChange hooks, the public file list, and the invalidation itself.
  • It waits only for the processing of that path, which it takes right after applying the message, so a slow change of another file does not delay it.
  • HMR runs afterwards and is not awaited.
• The promise rejects with an error that names the operation, the path and the Worker, when:
  • a Worker fails to apply the change, for example when a plugin's watchChange hook throws (the Web Worker used to only log this);
  • the Web Worker reports an error event;
  • the answers do not arrive within the new fileSyncTimeout option (10 seconds by default);
  • the instance is disposed first.
• Answers with unknown ids, such as those for another instance in the same page, and late answers are ignored.
• Binary content is copied for each target. Before, the caller's ArrayBuffer was transferred to the first target, which detached it.

Deletions are invalidated before HMR

moduleGraph.onFileDelete() keeps the deleted file's cached transform result. Vite clears it only during the HMR update (updateModules()), and never when server.hmr is false. The promise does not wait for HMR, so a read right after deleteFile() resolved could still get the deleted file's code.

Deletions now also call moduleGraph.onFileChange() before HMR, in the same order as changes. The integration test that holds the HMR update of a deletion fails without this.

Timeout

10 seconds is shorter than the 30-second RPC timeout between the Service Worker and the Web Worker, so with slow plugins an operation can reject although the change is applied later. The README and the option's JSDoc say to increase fileSyncTimeout in such environments, and that writing the file again resynchronizes it.

Known limitation: public files

The Service Worker builds its list of public files when it starts, when only /public/.gitkeep exists, and never updates it. I checked in the browser that a file under /public/ is not served at the preview root, whether it is passed to ready() or added later. The request gets the SPA fallback index.html instead.

This PR does not change that. The README and the JSDoc of addFile() state the limitation, and the fix is left for a separate issue.

Out of scope

• @vrowzer/fs's initFiles() passes the same transfer list to every target. With two or more targets and binary files, the second postMessage() should therefore fail on a detached ArrayBuffer. Vrowzer does not use initFiles(). I found this by reading the code and did not reproduce it.
• Resynchronizing after a Service Worker restart (Recover project files and channels after Service Worker process restart #46), and sharing the Service Worker between clients (Isolate projects sharing a Service Worker registration #45).

Tests

• Unit tests:

  • @vrowzer/fs: ids on messages, V_FS_ACK, and binary copies. A test with a real MessageChannel checks that the caller's buffer stays usable.
  • vite-dev-server: waitForFileChange() waits for watchChange and invalidation but not for HMR, rejects when watchChange fails, keeps the events of the same path separate, and forgets events that settled without being taken.
  • The Web Worker and Service Worker cores acknowledge a message after applying it, with the error when applying fails.
  • Vrowzer, using fake timers where timing matters:
    • both answers are required;
    • error answers;
    • the timeout;
    • Web Worker errors;
    • unknown and late answers;
    • two instances in one page;
    • the states other than ready;
    • binary copies;
    • a failure to send;
    • disposal.
  • All new tests failed before the change, except two that check behavior kept unchanged.

• Integration tests in the shared playground. A Web Worker test plugin holds or fails watchChange, and holds the HMR update of deletions. The tests check that:

  • an update stays pending while the Web Worker has not invalidated the module, reads still get the cached result in the meantime, and reads after it resolves get the new content;
  • adding, updating, writing the same content, adding an unused file, deleting, deleting again and re-adding all resolve, and reads follow them;
  • binary content reaches both Workers with the same bytes, and the caller's buffer stays usable;
  • a failed change rejects, and writing the file again converges;
  • a deletion is visible before its HMR update finishes.

  The tests fail when the Web Worker answers without waiting for invalidation, or when only HMR invalidates deletions.

  They read through the Service Worker from the host page. A read from the preview iframe could be interrupted by an HMR full reload of the iframe, which made one run fail.

• The existing integration tests and the e2e helpers now wait for the file operations.

Validated locally with:

• vp run test:unit: 118 files, 1,901 tests
• vp run test:integration:vrowzer: 60 passed and 1 conditional skip, in three consecutive runs
• vp run test:e2e: 46 passed, 6 existing test.skip
• oxlint (no new warnings), knip, the format check of the changed files, and typecheck