English | 中文
class-fetch
is a js library for generating HTTP clients, written in TypeScript.
- Based on fetch, it supports browser and nodejs runtime.
- It uses decorators to simplify the handling of request parameters and return values.
- It uses
class-transformer
andclass-validator
to implement data transformation and validation. - It has rich type constraints.
- It is inspired by WebApiClient.
npm install class-fetch
Note that class-fetch
has the following libraries as peerDependencies, and your project needs to include them:
class-transformer
class-validator
cross-fetch
Please make sure these libraries are installed in your project.
import {
Fetch,
Get,
Param,
ReturnType,
autoImplement,
build,
t,
} from "class-fetch";
class Posts {
public id!: number;
public title!: string;
public body!: string;
public userId: number;
}
@Fetch("https://jsonplaceholder.typicode.com/posts")
class Foo {
@Get(t`${"id"}`)
@ReturnType(Posts)
public get(@Param("id") id: string): Promise<Posts> {
autoImplement();
}
}
const foo = build(Foo);
(async () => {
console.log(await foo.get("7")); // get https://jsonplaceholder.typicode.com/posts/7
})();
class-fetch
can be divided into four stages when making a request:
- build: Initialize the request, set the URL and other basic Request configurations.
- prettyRequest: Decorate the request, modify the path, headers, query parameters and body configurations.
- middleware: Execute middleware functions, intercept and process requests and responses.
- transformResponse: Transform the response, according to the type and processing method of the return value, transform and verify the Response.
The decorators work throughout these four stages, each with some priority, exclusivity and necessity.
In this stage, you need to use the following two decorators::
Fetch
: Used to decorate the class that will serve as the HTTP client template, and configure the basic Request. It can only be used singly and must have one.Method
: Used to decorate the instance method that will be automatically implemented, and specify the HTTP method of the request. It can only be used singly and must have one.
The priority of these two decorators is: Fetch
> Method
.
Method
has some convenient wrappers: Delete
, Get
, Post
, Put
.
This stage will handle the parameters on the instance method, further decorate the Request. Affected by the following decorators:
Param
:Instantiate the template path configured byMethod
with the corresponding actual parameter.Apply
: Used to decorate Request options.RawBody
: Use the corresponding actual parameter as the raw body data.Body
: Use built-in plugins to automatically encode body data.
The priority of these decorators is: Param
> Apply
> RawBody
or Body
.
Apply
has some convenient wrappers: Header
, Query
, RequestInit
.
This stage is affected by the Middleware
decorator.
You can use Middleware
on classes and instance methods, or configure middleware through the client factory’s use method.
The priority of these middleware is: use > class > method.
In this stage, you need to use one of the following two decorators:
Return
: Use a callback to handle the request context, and the return value will be used as the return value of the corresponding instance method.ReturnType
: Use built-in plugins to decode and verify Response’s body usingclass-transformer
andclass-validator
.
Note that Return
and ReturnType
are mutually exclusive and can only use one of them.
You can use the ReThrow
decorator to decorate classes and instance methods, handle exceptions thrown in prettyRequest, middleware, transformResponse stages, and finally rethrow them.