Hello again everyone. āSpringā might be here, but if you live in the northeastern United States like I do, you know we still might have a little more wintry weather to go.
Still, the potential for lousy weather canāt stop a new version of the library being released ā 1.1.0 ā and it has some new features:
Support for TypeScript 5.0
And better yet, still able to support TypeScript 4.5 and up.
WKRequestFactory and Request Types
Documentation
In version 1.0, I provided a means for converting a Parameters object (i.e. when requesting a Collection) into a string, to be appended onto the end of the URL for the given resource. So a request to get a userās lessons might start with something like this:
const params: WKAssignmentParameters = {
immediately_available_for_lessons: true,
}
const url = `https://api.wanikani.com/v2/assigmnents${stringifyParameters(params)}`;
const headers = {
Authorization: `Berer ${SECRET_API_TOKEN}`,
"Wanikami-Revision": WK_API_REVISION,
};
const init: RequestInit = {
headers,
}
const response = await fetch(url, init);
if (!response.ok) {
throw new Error(`HTTP Error ${response.status}`);
}
But if you sent that request, youād throw an error, cause WaniKani would respond with HTTP Error 401. Fix that, and now it throws due to HTTP Error 404. Fix that, and while youāll get the data youād expect today, if WaniKani bumps their API revision, youāll still get data from revision 20170710!
For those who prefer to do this sort of thing programmatically, you can use WKRequestFactory to build complete, type-safe requests to the API. The example above becomesā¦
const params: WKAssignmentParameters = {
immediately_available_for_lessons: true,
}
const wk = new WKRequestFactory(
{
apiToken: SECRET_API_TOKEN,
revision: WK_API_REVISION,
}
);
const { url, headers } = wk.assignments.get(params);
const init: RequestInit = {
headers,
}
const response = await fetch(url, init);
if (!response.ok) {
throw new Error(`HTTP Error ${response.status}`);
}
And of course, if you donāt like or donāt have access to the Fetch API, the returned WKRequest objectās properties can be used in whichever HTTP API/Library you prefer or need to use. Thereās also options available to set additional headers for one or all requests noted in the documentation.
If you canāt or donāt want to use the entire factory to build out your requests, thatās fine, too! The WKRequestHeaders interface can help make sure your requestās headers are named and formatted properly (e.g. saying Bearer, not Berer for the Authoriztion header, setting valid Accept and Content-Type headers, offering autocomplete for editors, etc.), and stringifyParameters will always be around to append onto resource URLs just like before.
Subject Markup Matchers
A new object WK_SUBJECT_MARKUP_MATCHERS provides Regex Literals for the Japanese text, Radical/Kanji/Vocab names, meanings/readings, etc. found in the subject meaning/reading mnemonics and hints. They have a named capturing group, innerText, that can be accessed on methods like String.prototype.matchAll().
For instance, if youāre building a React-powered website, you may want to stylize Radical names similar to WaniKaniās site.
import { WK_SUBJECT_MARKUP_MATCHERS } from "@bachmacintosh/wanikani-api-types/dist/v20170710";
import reactStringReplace from "react-string-replace";
reactStringReplace(
'The <radical>ground</radical> moves under my feet.',
WK_SUBJECT_MARKUP_MATCHERS.radical,
(match, i) => (
<span className="bg-light-blue text-white font-bold">
{match}
</span>
));
/*
=> [
'The ',
<span className="bg-light-blue text-white font-bold">ground</span>,
' moves under my feet.'
]
*/
For info on the methods available on these patterns, see RegExp. Note that these regex literals are global, something to keep in mind when using certain string and regex methods.
Validators
If you need to do runtime validation of Parameter and/or Payload objects, or are running into weird TypeScript type-widening behavior on the Parameter types that you need to step around, the validateParameters() and validatePayload() helper functions are what you need. They throw a TypeError if the object is missing or has unexpected properties. And of course, these can be used when making requests to catch errors before you actually send or request data via the API; I even use them in the already-mentioned WKRequestFactory methods.
As always, any feedback or issues are welcome here or on GitHub. The library has over 99% test coverage, but you never know about that less than 1% chance of a bug or other weird behavior.
Otherwise, see you in a couple months with version 1.2, which will support TypeScript 5.1 ā any new features yet to be determined.
