Brandon Keepers - I'm working on new API docs t...
I'm working on new API docs that will replace the built-in server docs. You can browse a WIP build here[1]. There's still a lot of work to do (especially to clean up the generated API docs), but I'd love feedback on the PR[2].
Specifically, I am focusing my attention around Plugin [3], and ServerAPI [4], but open to any and all suggestions.
[1]: https://opensoul.org/signalk-server/
[2]: https://github.com/SignalK/signalk-server/pull/1914
[3]: https://opensoul.org/signalk-server/_signalk/server-api/Plugin/
[4]: https://opensoul.org/signalk-server/_signalk/server-api/ServerAPI/
14 Replies
đź‘Ť
there are many branded strings like SourceRef, but the docs don't show that they are actually strings underneath. but is it enough that your IDE tells you that?
Interesting. I'll look into it.
I made a change that will at least show the type declaration, so that helps a little. I added some docs for
Brand as well. https://opensoul.org/signalk-server/_signalk/server-api/Brand/
Honestly not sure I love the use of Branded types for a public API like this.
why?
on the other hand i am not fond of dealing with just strings and not having any support from types
I get doing it in a large self-contained application where you're trying to add clarity and specificity to domain logic, but for a public API that is used by people who may not be as comfortable with the domain, I worry it could be cumbersome. I find it unintuitive, and I'm well-versed in TypeScript.
I'm loving having these types in the editor though. I almost have streambundle converted to TS with full types for BaconJS. Just 3 errors left
Re: branded types for paths specifically, I'm think we can convert the JSON schema to TypeScript and be able to autocomplete paths
Another example of why I'm skeptical of branded types. You end up having to cast them back when calling common methods
Sorry to keep piling on, but another example. I'm working through typescript issues in #1917, and just switching from
any to the proper type causes errors due to branded types.
neither of these are due to branding - i am not aware of any typing solution that would discern between strings and Paths and require no code modifications. so to me it is not a question of branded types, but typing the strings in the first place
the upside to me is that this helps you document & understand things - it is more than the name of a variable/parameter to tell you what is what
as for solutions
- Object.keys will always return plain strings => switch to Set or add the cast
- add vesselContextFromId utility function
and to be clear: i am EXTREMELY happy to have more eyes and hands on this!
Not sure I understand. If
path was just a string, then data.context = 'vessels.' + app.selfId would not require any modifications. But since it's a branded string, it requires an as Path cast.
There's no way to create a Path without forced casting, which starts to decrease the utility of TypeScript in the first place
I just don't see what you gain by forcing users to use as Path, when I can cearly see from a
…api docs and editor hints that it's a path
I'll keep forging ahead as is, but just trying to share feedback on what feel like sharp edges from the perspecive of fresh eyes
Maybe once everything is in TypeScript and typings are complete it won't be as bad, but in this intermediate state it feels like there is a lot of as casting happening in the code base (especially to any, but encouraging casting in any form opens up a can of worms). It feels like a code smell to me.yeah, codebases converted halfway have that smell of
any s and as s
I am looking at the types in Server API as something you should be using in your plugin code - not just at the edge, when your code calls the server API, but all over the codebase
so that the compiler helps you not mix vessel.selfId and plain selfId, when the variable name is just self
..but i also get that it is not without the problemsBuild failing after merge https://github.com/SignalK/signalk-server/actions/runs/14300603875/job/40074310389#step:4:1153
GitHub
docs: New built-in docs that include Server API docs for plugin dev...
An implementation of a Signal K central server for boats. - docs: New built-in docs that include Server API docs for plugin devel… · SignalK/signalk-server@1785734