Add WebIDLs for Filesystem Access API

[Speak2Erase]

IDL, MDN Docs

I'm pretty new to contributing to projects like this, please lmk if I did something wrong!

I followed the basic instructions listed in web-sys's Readme.

As far as I can tell, the bindings are correct. However, I don't really know what I am doing, especially about [Throws], so that assumption could be wrong.

The Filesystem Access API seems to be pretty stable, however some browsers do not support it (i.e. Firefox) so I added it to unstable.

[daxpedda]

LGTM otherwise.
Needs a rebase though.

[daxpedda]

These functions don't throw, their Promise can reject with an exception, e.g. https://fs.spec.whatwg.org/#dom-filesystemfilehandle-getfile.

See https://searchfox.org/mozilla-central/source/dom/webidl/FileSystemFileHandle.webidl.

Suggested change

	[Throws]
	Promise<File> getFile();
	[Throws]
	Promise<FileSystemWritableFileStream> createWritable(optional FileSystemCreateWritableOptions options = {});
	[Exposed=DedicatedWorker, Throws]
	Promise<FileSystemSyncAccessHandle> createSyncAccessHandle();
	Promise<File> getFile();
	Promise<FileSystemWritableFileStream> createWritable(optional FileSystemCreateWritableOptions options = {});
	[Exposed=DedicatedWorker]
	Promise<FileSystemSyncAccessHandle> createSyncAccessHandle();

[daxpedda]

As above, none of these should throw: https://searchfox.org/mozilla-central/source/dom/webidl/FileSystemDirectoryHandle.webidl#6.

Suggested change

	[Throws]
	async iterable<USVString, FileSystemHandle>;
	[Throws]
	Promise<FileSystemFileHandle> getFileHandle(USVString name, optional FileSystemGetFileOptions options = {});
	[Throws]
	Promise<FileSystemDirectoryHandle> getDirectoryHandle(USVString name, optional FileSystemGetDirectoryOptions options = {});
	[Throws]
	Promise<undefined> removeEntry(USVString name, optional FileSystemRemoveOptions options = {});
	async iterable<USVString, FileSystemHandle>;
	Promise<FileSystemFileHandle> getFileHandle(USVString name, optional FileSystemGetFileOptions options = {});
	Promise<FileSystemDirectoryHandle> getDirectoryHandle(USVString name, optional FileSystemGetDirectoryOptions options = {});
	Promise<undefined> removeEntry(USVString name, optional FileSystemRemoveOptions options = {});

[daxpedda]

According to the spec all three can throw: https://streams.spec.whatwg.org/#writablestream-get-a-writer.
Not sure why Firefox doesn't have it: https://searchfox.org/mozilla-central/source/dom/webidl/FileSystemWritableFileStream.webidl.

Suggested change

	Promise<undefined> write(FileSystemWriteChunkType data);
	Promise<undefined> seek(unsigned long long position);
	Promise<undefined> truncate(unsigned long long size);
	[Throws]
	Promise<undefined> write(FileSystemWriteChunkType data);
	[Throws]
	Promise<undefined> seek(unsigned long long position);
	[Throws]
	Promise<undefined> truncate(unsigned long long size);

[djozis]

Hi @daxpedda, I tried this in Chrome with this sample:

    const storage = await window.navigator.storage.getDirectory();
    const fileHandle = await storage.getFileHandle('test', { create: true });
    const writable = await fileHandle.createWritable();
    const writer = writable.getWriter(); // lock the stream
    try {
        console.log(writable.write('x')); // will fail to get a writer internally
    } catch(e) {
        // this won't run, instead the above promise will fail
        console.log("CAUGHT");
        console.log(e);
    }

I know you linked docs about getting a writer for a writablestream - but it seems this write function returns a promise which fails in the case that getting a writer fails due to the stream being locked, rather than throwing directly. Based on that, I think that like the Firefox webidls, that these should not have the [Throws] annotation, because they give a failed promise instead of throwing when a writer can't be obtained for the stream.

What do you think? Am I missing something? :)

I'm happy to submit another PR to correct this if you agree.

[djozis]

I created a PR for this, can continue discussion there perhaps: #3435

[djozis]

Hopefully not a faux pas, but I wanted this too, including the PR feedback, so I made the changes for my personal use, and thought I'd offer it back here: #3427

[Speak2Erase]

Oh, tysm! I don't have much time to fix up this PR. I've been meaning to for a few days now.
If you're okay with continuing #3427, I'd be happy to close this one.

[daxpedda]

Closing in favor of #3427.