denoland / denoland/eszip

JS API is not idiomatic or documented

Open
#135 0 comments 1 reaction 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.