feat(rpc): document every export with JSDoc, add getBalance and Valid… - #15
Open
thethclup wants to merge 1 commit into
Open
feat(rpc): document every export with JSDoc, add getBalance and Valid…#15thethclup wants to merge 1 commit into
thethclup wants to merge 1 commit into
Conversation
…ationError The SDK was announced publicly as "a fully typed, documented toolkit to query the chain and ship apps." Three things stood between that pitch and the code a new developer meets after `npm i`. Docs were Python-style `Args:`/`Returns:` docstrings, a port artifact from the Python SDK: editors render them as one undifferentiated paragraph, so hovering a parameter told you nothing, and they referenced `ValueError`, an exception this SDK never throws. Every public export in rpc.ts now carries a real JSDoc block -- description, @PARAM, @returns, @throws, and a runnable @example -- so the answers surface inline in the editor. Reading a balance meant calling account(), receiving a Record<string, any>, and knowing to reach for `amount` -- a field name discoverable only by reading the e2e tests. getBalance() returns it as a zod-validated number, with the same `height` option for historical lookups. Argument validation threw a plain Error, so an invalid address -- the most common mistake a new developer makes -- was the one failure that escaped the CanopyError hierarchy the README promises. It now throws ValidationError, carrying the offending input on `.value`. Centralizing the address/hash checks (previously copy-pasted across six functions) also closed two gaps: they verified length but not hex content, so a 40-character non-hex string reached the node and came back as an opaque RPC failure, and NaN slipped past the `< 0` guards on height and ID arguments. Both are now rejected up front. Tests: 42 new unit tests covering getBalance and validation across every argument-taking export; e2e smoke coverage asserting getBalance agrees with the raw account query against a live devnet. 285 unit tests pass, build clean.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
…ationError
The SDK was announced publicly as "a fully typed, documented toolkit to query the chain and ship apps." Three things stood between that pitch and the code a new developer meets after
npm i.Docs were Python-style
Args:/Returns:docstrings, a port artifact from the Python SDK: editors render them as one undifferentiated paragraph, so hovering a parameter told you nothing, and they referencedValueError, an exception this SDK never throws. Every public export in rpc.ts now carries a real JSDoc block -- description, @PARAM, @returns, @throws, and a runnable @example -- so the answers surface inline in the editor.Reading a balance meant calling account(), receiving a Record<string, any>, and knowing to reach for
amount-- a field name discoverable only by reading the e2e tests. getBalance() returns it as a zod-validated number, with the sameheightoption for historical lookups.Argument validation threw a plain Error, so an invalid address -- the most common mistake a new developer makes -- was the one failure that escaped the CanopyError hierarchy the README promises. It now throws ValidationError, carrying the offending input on
.value.Centralizing the address/hash checks (previously copy-pasted across six functions) also closed two gaps: they verified length but not hex content, so a 40-character non-hex string reached the node and came back as an opaque RPC failure, and NaN slipped past the
< 0guards on height and ID arguments. Both are now rejected up front.Tests: 42 new unit tests covering getBalance and validation across every argument-taking export; e2e smoke coverage asserting getBalance agrees with the raw account query against a live devnet. 285 unit tests pass, build clean.