DEV Community: shindex

Type-safe HTTP requests with Nuxt

shindex — Mon, 04 May 2020 08:29:25 +0000

Problems with HTTP requests

Type inference for HTTP requests in the editor is not enough. Any change in the API reference requires a change in the source code, which is a very tedious and error-prone process.

Aspida is the OSS that solves it.
For a more detailed explanation of ASPIDA, please see the following article.

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

This article presents an example of a type-sefe HTTP request in the Nuxt environment using Aspida.

Building typescript environment with Nuxt

It used to be a little difficult, but now you can easily build a typescript environment just by using the create-nuxt-app.

$ npx create-nuxt-app aspida

create-nuxt-app v2.15.0
✨  Generating Nuxt.js project in aspida
? Project name aspida
? Project description My exceptional Nuxt.js project
? Author name shindex
? Choose programming language TypeScript
? Choose the package manager Npm
? Choose UI framework None
? Choose custom server framework None (Recommended)
? Choose the runtime for TypeScript @nuxt/typescript-runtime
? Choose Nuxt.js modules Axios
? Choose linting tools (Press <space> to select, <a> to toggle all, <i> to invert selection)
? Choose test framework None
? Choose rendering mode Universal (SSR)
? Choose development tools (Press <space> to select, <a> to toggle all, <i> to invert selection)

In the Choose programming language field, select typescript.
Also, since we'll be using axios later, let's select axios in the Choose Nuxt.js modules section.

Let's go to the aspida directory that was created.

$ cd aspida

Now you are ready to use typescript in nuxt!

Building an ASPIDA environment

First, you need to install aspida.

$ npm install @aspida/axios

Edit the package.json.

{
  ...

  "scripts": {
    "dev": "aspida --watch & nuxt-ts",   // this line is edited.
    "build": "nuxt-ts build",
    "generate": "nuxt-ts generate",
    "start": "nuxt-ts start",
  },

  ...
}

Registering $api in nuxt plugins. Create plugins/api.ts.

import { Plugin } from '@nuxt/types'
import axiosClient from '@aspida/axios'
import api, { ApiInstance } from '~/apis/$api'

declare module 'vue/types/vue' {
  interface Vue {
    $api: ApiInstance
  }
}

const plugin: Plugin = ({ $axios }, inject) => inject('api', api(axiosClient($axios)))

export default plugin

Edit the nuxt.config.js. This time, we will use an API called Hello, salut!, which returns country code and a greeting when you give a language code.

export default {
  ...

  plugins: [
    '~/plugins/api'
  ],

  axios: {
    baseURL: 'https://fourtonfish.com/'
  },

  ...
}

Hello, salut! doesn't work without a / just before the query.

Correct : https://fourtonfish.com/hellosalut/?lang=en
Incorrect: https://fourtonfish.com/hellosalut?lang=en

By writing a configuration file, you can solve various problems like this. The Aspida configuration file is written in the project root, aspida.config.js.

module.exports = { trailingSlash: true }

Create a type definition file

Create the required types at /apis/@types.ts. This file should only contain the type. The following types are the response types for Hello, salut!.

export type Greeting = {
  code: string
  hello: string
}

Write the type definition for the http request in apis/hellosalut/index.ts.

import { Greeting } from '~/apis/@types'

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

Now, let's start nuxt.

$ npm run dev

apis/$api.ts is generated at the same time as nuxt is started.

It's going very well. Let's restart the editor here to reload the type inference.

Using type-secure HTTP requests

Now, take a look at an HTTP request using aspida. The following is pages/example.vue.

<template>
  <table>
    <thead>
      <tr>
        <th>country code</th>
        <th>greeting</th>
      </tr>
    </thead>
    <tbody>
      <tr v-for="greeting in greetings" :key="greeting.code">
        <td>{{ greeting.code }}</td>
        <td>{{ greeting.hello }}</td>
      </tr>
    </tbody>
  </table>
</template>

<script lang="ts">
import Vue from 'vue'
import { Greeting } from '~/apis/@types'

export default Vue.extend({
  data() {
    return {
      greetings: [] as Greeting[]
    }
  },

  async fetch() {
    const langs = [ 'en', 'zh', 'de', 'fr', 'ja' ]

    this.greetings = (
      await Promise.all(
        langs.map((lang) => this.$api.hellosalut.$get({ query: { lang } }))
      )
    ).map(({ code, hello }) => ({
      code,
      hello: hello.startsWith('&#')
        ? String.fromCharCode(
            ...hello
              .slice(2, -1)
              .split(';&#')
              .map((n) => +n)
          )
        : hello
    }))
  }
})
</script>

type inference does not work in asyncData. Let's use fetch instead.
You can access the $api from this.

You can see that it is possible to write an HTTP request type-sefely as follows.

Aspida warns you of your mistakes.

Run npm run dev and check the localhost:3000/example.

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

shindex — Fri, 01 May 2020 11:10:57 +0000

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   :  こんにちは