@bachman-dev/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).

| Package Version | TypeScript Versions | WaniKani API Version | Latest API Revision | | --------------- | ------------------- | -------------------- | ------------------- | | 2.x | 5.0 - 5.9 | 2 | 20170710 | | 1.x | >= 4.5 | 2 | 20170710 |

Install

NPM / Yarn / pnpm / Deno / Bun

Run the following command pertaining to your package manager:

npm install @bachman-dev/wanikani-api-types

yarn add @bachman-dev/wanikani-api-types

pnpm add @bachman-dev/wanikani-api-types

deno add npm:@bachman-dev/wanikani-api-types

bun add @bachman-dev/wanikani-api-types

Then, import using one of two methods.

Specific API Revision (Recommended)

The module you import from matches a WaniKani API Revision; you shouldn't expect any breaking changes from the package.

import * as WK from "@bachman-dev/wanikani-api-types/v20170710";

Latest API Revision (Not Recommended)

Importing from the index module will always provide types, methods, etc. for use with the latest and greatest API Revision.

import * as WK from "@bachman-dev/wanikani-api-types";

Other Environments

You can import the modules directly with esm.sh.

Be sure to replace x.y.z with your desired version number.

Specific API Revision (Recommended)

The module you import from matches a WaniKani API Revision; you shouldn't expect any breaking changes from the package.

import {
  type AssignmentParameters,
  DatableString,
} from "https://esm.sh/@bachman-dev/[email protected]/v20170710";
import { ApiRequestFactory } from "https://esm.sh/@bachman-dev/[email protected]/v20170710";

Latest API Revision (Not Recommended)

Importing from the index module will always provide types, methods, etc. for use with the latest and greatest API Revision.

import { type AssignmentParameters, DatableString } from "https://esm.sh/@bachman-dev/[email protected]";
import { ApiRequestFactory } from "https://esm.sh/@bachman-dev/[email protected]";

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
• 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

Schema Validation

If you need to validate data going to/from the WaniKani API at runtime, you can use matching Valibot schema provided for every exported type to do so; these schema are also compatible with any Standard Schema compatible application/library.

Type Guards

For all the types representing items coming from the WaniKani API, we provide type guards to quickly validate if the data matches a type (e.g. a WaniKani resource, or an API error if something went wrong), without producing any side-effects to keep your application's bundle size small.

Request Factory

We provide a special class, ApiRequestFactory, 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.

Markup Matcher

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 a Regex literal that can be used to extract one or more of these sorts of markup in SUBJECT_MARKUP_MATCHER.

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:

• https://github.com/bachman-dev/wanikani-api-types/blob/main/CONTRIBUTING.md
• https://github.com/bachman-dev/wanikani-api-types/blob/main/CODE_OF_CONDUCT.md

Thank you in advance for your contribution(s)!