JS API is not idiomatic or documented
- Dominant language
- TypeScript
- Stars
- 286
- Forks
- 30
- PR merge metrics
- No merged PRs in 30d
Description
It seems like the only way to know how to even use the JS API is to dig into the Rust code. The generated documentation at https://deno.land/x/eszip@v0.45.0/mod.ts is completely useless.
I think the following changes should be made:
- Make `Parser` wrap `InternalParser`, rather than extend it.
- Since all of the methods of `(Internal)Parser` return promises, make the `Parser` constructor synchronous and initialize the wasm module on the first method call. We can still keep `createInstance` for backward compatibility.
- Can we make `Parser::parse` take a `ReadableStream` and have it acquire a BYOB reader, rather than take the BYOB reader? Or maybe have the JS-side `parse` method wrapper take a `ReadableStream | ReadableStreamByobReader`.
- Making `Parser` a wrapper class would take care of having the methods and their argument/return types in the documentation, but there needs to be more documentation on top of that.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the generated documentation at https://deno.land/x/eszip@v0.45.0/mod.ts and the mod.ts entry point. Compare the documented JS-facing Parser, InternalParser, createInstance, and parse APIs with the requested constructor, stream, wrapper, and documentation changes. Done means the API is idiomatic and documented while createInstance remains available for backward compatibility.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, typescript
- Domain
- api, developer-experience, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 28/100