Add webidl iterable support

[RaoulHC]

Was trying to figure out how to list files in OPFS before I realised these methods were just missing from web-sys.

Added some tests that use these and more generally test some of the file system API, only tested it with geckodriver but it should be well supported across all browsers.

Also added some flags so that the optional stream module should get generated in docs.rs too, wasn't obvious it existed, and it's somewhat needed to make use of the AsyncIterator that these methods return.

[RaoulHC]

Oh I see I missed that the web-sys files are generated from webidl, and that the async iterable field is what should be providing the entries/keys/values methods. Given the following code am I right in thinking this isn't currently supported?

wasm-bindgen/crates/webidl/src/first_pass.rs

Lines 561 to 567 in fa6d2bc

	InterfaceMember::AsyncIterable(_iterable) => {
	log::warn!(
	"Unsupported WebIDL async iterable interface member: {:?}",
	self
	);
	Ok(())
	}

[Liamolucko]

Given the following code am I right in thinking this isn't currently supported?

wasm-bindgen/crates/webidl/src/first_pass.rs

Lines 561 to 567 in fa6d2bc

	InterfaceMember::AsyncIterable(_iterable) => {
	log::warn!(
	"Unsupported WebIDL async iterable interface member: {:?}",
	self
	);
	Ok(())
	}

Yes; there's an old issue #514 about it.

[RaoulHC]

Yes; there's an old issue #514 about it.

Yep found that and am getting something working, looks like it's relatively simple to add, most of the plumbing is already there, so will update this PR.

[RaoulHC]

I've got something working that I've pushed, wasn't sure how to do the async forEach method so I've left that for now, I think most users will probably want to use the futures Stream interface via JsStream anyway.

Looking at how the ergonomics could be improved given we know the types yielded for these cases, some ideas in that issue so will see if something can work.

[RaoulHC]

Playing around with it a bit, I think the neatest way might be leave the exposed js methods (maybe prepend with a js_?) but also generate a shim that uses the type information to give a generate an (async) iterator that uses unchecked_into to massage it into something nicer to deal with in rust.

So for FileSystemDirectoryHandle it'd be something like this:

impl FileSystemDirectoryHandle
   pub fn entries() -> impl Stream<Item = (JsString, FileSystemHandle)> {
       JsStream::from(self.js_entries()).map(|x| {
            let array = x.unwrap().unchecked_into::<Array>();
            (array.at(0).unchecked_into(), array.at(1).unchecked_into())
        })
    }
}

with something similar for regular iterables, and without the array step for keys and values, which only return the one item.

Thoughts? It seems like there was a bunch of discussions regarding iterators but the direction was never really settled and a lot of those main contributors are no longer on wasm-bindgen, Probably need to read a bit more into if there are ever any cases where iterables for some of these methods can throw errors, but hand writing this for the directory case works fairly nicely with the tests I have.

[RaoulHC]

I've had a bit of a crack at this, but how you massage the types was trickier than I thought, Web IDL has types that JS doesn't so to cast to equivalent rust types you have to go via js types which doesn't always cast simply. Some API's generate enums that I also wasn't sure exactly how to deal with (see MediaKeyStatus in MediaKeyStatusMap. There's also the question of whether we want to stick to Js values (i.e. JsString and js_sys::Number) or convert to rust values closer to what Web IDL specifies: sticking to js values means there wont be unnecessary copies, but you lose some of the type information specified for the API.

I think for now exposing these methods that just return js iterators allows users to at least use the iterable interfaces, they'll just have to deal with casting to the types they want. Maybe we want to gate it behind a feature flag if we plan on changing the API later.

[daxpedda]

LGTM!
Just missing a changelog entry.

I know that the current state isn't ideal with the fact that we don't encode the types that we are already able to parse from the WebIDL, but this will require much more design work and probably best to leave to a future breaking change.

Would appreciate your approval on this as well @Liamolucko.

[daxpedda]

Array::for_each() takes a &mut dyn FnMut() instead, which also can encode types. Both ways have tradeoffs and ideally we could have both, so I'm happy to leave it as is because I think it aligns more with all the other APIs web-sys currently exposes.

[RaoulHC]

Yeah while I think we eventually want that, I think it will need shims that aren't so easy to generated as I struggled with for the entries and co API too. Can write a new issue for doing this specifically (although maybe it fits one of the existing related issues already, and that just needs an update).

[daxpedda]

Probably be best to wait for demand first.
But I appreciate the offer!

[RaoulHC]

Rebased, added a changelog entry and updated the CI so I think this should be good to go in now.

[RaoulHC]

Not sure what the typescript test failure is, but I seem to be getting it on main too, so it's unrelated to my change.

[daxpedda]

Rebased, added a changelog entry and updated the CI so I think this should be good to go in now.

Apologies for the delay!

Not sure what the typescript test failure is, but I seem to be getting it on main too, so it's unrelated to my change.

That was fixed in #4016.

[daxpedda]

Probably be best to wait for demand first.
But I appreciate the offer!