@bachmacintosh/wanikani-api-types

Regularly updated type definitions for the WaniKani API

Documentation

Available at https://wanikani-api-types.bachman.dev

Package Versioning

This project follows Semantic Versioning, with versions formatted as x.y.z.

A new Patch Version z includes backwards-compatible bug fixes, corrections to documentation, and other relatively insignificant changes.

A new Minor Version y includes new backwards-compatible library features, new backwards-compatible WaniKani API changes (e.g. new revision, new fields on a resource, etc.), widened TypeScript version support, and deprecatiung (but not removing) existing features to be removed in the next major version.

A new Major Version x includes backwards-incompatible changes such as removing previously deprecated items, backwards-incompatible WaniKani API changes (e.g. removing a field on a resource), or a breaking change in TypeScript that's introduced into the library (we'll try to avoid these as much as possible).

Install

NPM / Yarn / pnpm

npm install @bachmacintosh/wanikani-api-types
Copy

yarn add @bachmacintosh/wanikani-api-types
Copy

pnpm install @bachmacintosh/wanikani-api-types
Copy

import type { WKAssignmentParameters, WKDatableString } from "@bachmacintosh/wanikani-api-types/dist/v20170710";
import { stringifyParameters } from "@bachmacintosh/wanikani-api-types/dist/v20170710";
Copy

import type { WKAssignmentParameters, WKDatableString } from "@bachmacintosh/wanikani-api-types";
import { stringifyParameters } from "@bachmacintosh/wanikani-api-types";
Copy

Deno via NPM Specifier

import type {
  WKAssignmentParameters,
  WKDatableString,
} from "npm:@bachmacintosh/wanikani-api-types@x.y.z/dist/v20170710";
import { stringifyParameters } from "npm:@bachmacintosh/wanikani-api-types@x.y.z/dist/v20170710";
Copy

import type { WKAssignmentParameters, WKDatableString } from "npm:@bachmacintosh/wanikani-api-types@x.y.z";
import { stringifyParameters } from "npm:@bachmacintosh/wanikani-api-types@x.y.z";
Copy

Other Environments

import type {
  WKAssignmentParameters,
  WKDatableString,
} from "https://esm.sh/@bachmacintosh/wanikani-api-types@x.y.z/dist/v20170710.js";
import { stringifyParameters } from "https://esm.sh/@bachmacintosh/wanikani-api-types@x.y.z/dist/v20170710.js";
Copy

import type { WKAssignmentParameters, WKDatableString } from "https://esm.sh/@bachmacintosh/wanikani-api-types@x.y.z";
import { stringifyParameters } from "https://esm.sh/@bachmacintosh/wanikani-api-types@x.y.z";
Copy

Usage

Type Definitions

We provide various type definitions to help with sending/receiving type-safe elements to/from the WaniKani API.

• Base Types that define essential WaniKani API building blocks
• Collections/Reports/Resources that represent whole responses from the API
• Data that represents only the actual returned data from the API (i.e. the data field on most responses)
• Parameter Types that can be broken down into a query string to append to a URI for the API (especially when fetching Collections) -- see below.
• Payloads that represent JSON bodies sent to the API when creating/updating certain resources

We also export various subtypes that fall underneath these main types, in case they're needed to work with partial data.

Type Guards

Most of the types defined here are object types with straightforward structure. Sometimes, however, you may have a string or number that needs to meet specific criteria to be narrowed down to an exact type. So we provide some type guards to verify if a variable is of a given type; these will usually begin with is in their name (e.g. isWKDatableString). See the documentation for more info.

Request Factory

We provide a special class, WKRequestFactory, that returns Request objects with all the information you need to make a request to the WaniKani API. That means the request's method (GET, POST, PUT), the URL (with parameters for Collections or an ID for individual Resources), headers (Authorization, conditional headers, etc.), and a body if you are sending data. You can use these objects in your preferred HTTP API/Library such as the Fetch API, Axios, Needle, Node's https Module, etc.

Helper Functions

There are also multiple helper functions that can assist with formatting and/or validating data sent to the WaniKani API, outside of and in addition to the Request Factory.

• stringifyParameters converts a Parameters object (e.g. WKAssignmentParameters) into a URL query string to use when filtering a Collection
• validateParameters does runtime validation on a Parameters object, allowing for more strict validation than TypeScript's type narrowing behavior (i.e. not allowing widening to WKCollectionParameters); it's a good function for those who must be absolutely sure their parameters are of the exact type.
• validatePayload does runtime validation of Payload objects; while most TypeScript and editor-assisted projects likely won't need this function, it can be useful for pure JavaScript applications.

Markup Matchers

When working with WaniKani's Subjects, you may want to stylize/highlight the markup that's inside the reading/meaning mnemonics and hints. We provide some Regex Literals that can be used to extract one or more of these sorts of markup in WK_SUBJECT_MARKUP_MATCHERS.

Examples

See EXAMPLES.md for examples using this library.

Need Help? Want to Contribute?

Please note that this package is community-developed and is NOT officially supported by Tofugu LLC or its staff.

That said, if you have any questions or encounter any problems with this package, please feel free to open an Issue.

We welcome any contributions to help improve this library. Please see the following documents:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md

Thank you in advance for your contribution(s)!