"Aspida" is a tool to give types to HTTP clients

What is Aspida?

When you use an HTTP client, you often have a hard time because the type inference in the editor is not enough. If the API reference is changed or the URI is changed, the client has to modify the source code without type completion, which is very inconvenient.

Aspida, which is introduced in this article, is a tool that solves those problems. aspida allows HTTP clients such as axios and fetch to be given types in TypeScript. It can be used in a browser or Node.JS.

GitHub

How to install

Aspida can be installed using either npm or yarn.

Supported HTTP clients are: axios, ky, ky-universal, fetch, and node-fetch.

In this article, we will use axios as an example to illustrate.

$ npm install @aspida/axios axios

$ yarn add @aspida/axios axios

Preparation

First, let's create a directory to store the type definition file.

$ mkdir apis

Next, edit the package.json.

{
  "scripts": {
    "api:build": "aspida --build"
  }
}

How to use

Example of GET

Let's use Hello, salut!(https://www.fourtonfish.com/hellosalut/hello/) This is a public API that returns a country's greeting when you send a language code. You can check the API reference on the official page.

First, create an API definition file. The file name should match the API path.

// apis/hellosalut/index.ts

type Greeting = {
  code: string
  hello: string
}

export type Methods = {
  get: {
    query: {
      lang: string 
    }

    resBody: Greeting
  }
}

Next, execute the following command.

$ npm run api:build

> aspida@1.0.0 api:build /Users/shindex/js/aspida
> aspida --build

apis/$api.ts was built successfully.

Then, the $api.ts file will be generated in the /apis directory. This is the type definition file.

Now you're ready to use aspida. Let's feel the benefits of type completion.

Here is a sample.

// src/index.ts

import aspida from "@aspida/axios"
import api from "../apis/$api"

(async () => {
  const client = api(aspida(undefined, { baseURL:'https://fourtonfish.com' }))
  const res = await client.hellosalut.$get({ query: { lang: 'ja' } })

  console.log('county code: ', res.code) // county code: ja
  console.log(
    'greeting   : ',
    res.hello.startsWith('&#')
      ? String.fromCharCode(
          ...res.hello
            .slice(2, -1)
            .split(';&#')
            .map((n) => +n)
        )
      : res.hello
  ) // greeting: こんにちは
})()

The following image shows how type completion works in VSCode.
You can see that the type inference has been done perfectly.

Let's install a new module and run the above source code.

$ npm install ts-node typescript @types/node

$ yarn add ts-node typescript @types/node

Next, edit the package.json.

{
  "scripts": {
    "api:build": "aspida --build",
    "start": "ts-node src/index.ts"
  }
}

Run it!

$ npm start

> aspida@1.0.0 start /Users/shindex/js/aspida
> ts-node src/index.ts

county code:  ja
greeting   :  こんにちは