Aspida

TypeScript friendly HTTP client wrapper for the browser and node.js.

HTTP client • Fetch • AJAX
aspida/aspidaaspida

README

aspida


aspida

Features


- Path, URL query, header, body, and response can all specify the type
- FormData / URLSearchParams content can also specify the type
- HTTP client supports axios / fetch / node-fetch


vscode

Procedure


1. Reproduce the endpoint directory structure in the "api" directory
1. Export a Type alias named "Methods"
1. Call "aspida" with npm scripts
1. API type definition file "api/\$api.ts" will be generated, so import the application and make an HTTP request

Getting Started


Installation (axios ver.)


- Using npm:

  sh
  $ npm install aspida @aspida/axios axios
  

- Using Yarn:

  sh
  $ yarn add aspida @aspida/axios axios
  

Create "api" directory


  1. ```sh
  2. $ mkdir api
  3. ```

Type helper DefineMethods


DefineMethods<> is helper type for defining Methods. In earlier aspida, user shuold define without checking for API definition.
If you already have aspida in your projects, you can easily use DefineMethods<> with surrounding your definition.
It is just an option whether to use DefineMethods<>.
Be aware of the limitation that DefineMethods<> can't detect extra meaningless properties.

Create an endpoint type definition file


- GET: /v1/users/?limit={number}
- POST: /v1/users

  api/v1/users/index.ts

  ts
  import type { DefineMethods } from "aspida";

  type User = {
    id: number;
    name: string;
  };

  export type Methods = DefineMethods<{
    get: {
      query?: {
        limit: number;
      };

      resBody: User[];
    };

    post: {
      reqBody: {
        name: string;
      };

      resBody: User;
      /
       reqHeaders(?): ...
       reqFormat: ...
       status: ...
       resHeaders(?): ...
       polymorph: [...]
       */
    };
  }>;
  

- GET: /v1/users/\${userId}
- PUT: /v1/users/\${userId}

  api/v1/users/_userId@number/index.ts

  Specify the type of path variable “userId” starting with underscore with “@number”  
  If not specified with @, the default path variable type is "number | string"

  ts
  import type { DefineMethods } from "aspida";

  type User = {
    id: number;
    name: string;
  };

  export type Methods = DefineMethods<{
    get: {
      resBody: User;
    };

    put: {
      reqBody: {
        name: string;
      };

      resBody: User;
    };
  }>;
  

Build type definition file


package.json

  1. ```json
  2. {
  3.   "scripts": {
  4.     "api:build": "aspida"
  5.   }
  6. }
  7. ```

  1. ```sh
  2. $ npm run api:build

  4. > api/$api.ts was built successfully.
  5. ```

Make HTTP request from application


src/index.ts

  1. ```ts
  2. import aspida from "@aspida/axios";
  3. import api from "../api/$api";
  4. (async () => {
  5.   const userId = 0;
  6.   const limit = 10;
  7.   const client = api(aspida());

  9.   await client.v1.users.post({ body: { name: "taro" } });

  11.   const res = await client.v1.users.get({ query: { limit } });
  12.   console.log(res);
  13.   // req -> GET: /v1/users/?limit=10
  14.   // res -> { status: 200, body: [{ id: 0, name: "taro" }], headers: {...} }

  16.   const user = await client.v1.users._userId(userId).$get();
  17.   console.log(user);
  18.   // req -> GET: /v1/users/0
  19.   // res -> { id: 0, name: "taro" }
  20. })();
  21. ```

aspida official HTTP clients


- @aspida/axios
- @aspida/fetch
- @aspida/node-fetch

Command Line Interface Options


Option Type Default Description
--config
-c		 string "aspida.config.js" Specify the path to the configuration file.
--watch
-w		 Enable watch mode.
Regenerate $api.ts according to
        the increase / decrease of the API endpoint file.
--version
-v		 Print aspida version.

Options of aspida.config.js


OptionTypeDefaultDescription
--------------------------------------------------------------------------------------------------------------------
inputstring"api"Specifies
baseURLstring""Specify
trailingSlashbooleanfalseAppend
outputEachDirbooleanfalseGenerate
outputMode"all""normalOnly""aliasOnly"

Node.js API


  1. ```ts
  2. import { version, build, watch } from "aspida/dist/commands";

  4. console.log(version()); // 0.x.y

  6. build();
  7. build("./app/aspida.config.js");
  8. build({ input: "api1" });
  9. build([
  10.   { baseURL: "https://example.com/v1" },
  11.   {
  12.     input: "api2",
  13.     baseURL: "https://example.com/v2",
  14.     trailingSlash: true,
  15.     outputEachDir: true,
  16.     outputMode: "all",
  17.   },
  18. ]);

  20. watch();
  21. watch("./app/aspida.config.js");
  22. watch({ input: "api1" });
  23. watch([
  24.   { baseURL: "https://example.com/v1" },
  25.   {
  26.     input: "api2",
  27.     baseURL: "https://example.com/v2",
  28.     trailingSlash: true,
  29.     outputEachDir: true,
  30.     outputMode: "all",
  31.   },
  32. ]);
  33. ```

Ecosystem


- openapi2aspida - Convert OpenAPI 3.0 and Swagger 2.0 definitions
- aspida-mock - TypeScript friendly RESTful API mock
- frourio - Fast and type-safe full stack framework, for TypeScript TypeScript
- @aspida/react-query - React Query wrapper
- @aspida/swr - SWR (React Hooks) wrapper
- @aspida/swrv - SWRV (Vue Composition API) wrapper
- eslint-plugin-aspida - Support writing aspida api definition