adapters.ts
Quick, easy and type-safe way for declarative http endpoint definitions.
Quick Start
By default adapters.ts
provides two ready to use adapter classes:
- FetchAdapter that leverages the native browser fetch API
- AxiosAdapter that leverages the Axios library (axios needs to be installed separately)
but any http client library can be used with adapters.ts
.
Define a simple axios adapter
import { AxiosAdapter } from "adapters.ts";
class SwapiStarship extends AxiosAdapter {
static URL_TEMPLATE = "https://swapi.dev/api/starships/{id}";
}
SwapiStarship.get({ id: "1" }).then(
(response ) => {
console.log(response.data);
}
);
Adapter with type guards on received data
import { AxiosAdapter, DataType } from "adapters.ts";
class SwapiStarship extends AxiosAdapter {
static URL_TEMPLATE = "https://swapi.dev/api/starships/{id}";
static GET_RESPONSE_TYPE_DEF = DataType.RecordOf({
name: DataType.String,
model: DataType.String,
});
}
SwapiStarship.get({ id: "1" }).then(
(response ) => {
console.log(response.data);
}
);
Adapter with type guards on sent data
import { AxiosAdapter, DataType } from "adapters.ts";
class SwapiStarship extends AxiosAdapter {
static URL_TEMPLATE = "https://swapi.dev/api/starships";
static POST_REQUEST_TYPE_DEF = DataType.RecordOf({
name: DataType.String,
model: DataType.String,
});
}
SwapiStarship.post({
data: {
name: "CR90 Corvette",
model: "CR90 Corvette",
},
});
Disable/enable data validation on requests and responses
import { AxiosAdapter } from "adapters.ts";
class MyAdapter extends AxiosAdapter {
static URL_TEMPLATE = "https://url-goes.here";
static VALIDATE_REQUESTS = true;
static DELETE_REQUEST_TYPE_DEF = ;
static GET_REQUEST_TYPE_DEF = ;
static OPTIONS_REQUEST_TYPE_DEF = ;
static PATCH_REQUEST_TYPE_DEF = ;
static POST_REQUEST_TYPE_DEF = ;
static PUT_REQUEST_TYPE_DEF = ;
static VALIDATE_RESPONSES = true;
static DELETE_RESPONSE_TYPE_DEF = ;
static GET_RESPONSE_TYPE_DEF = ;
static OPTIONS_RESPONSE_TYPE_DEF = ;
static PATCH_RESPONSE_TYPE_DEF = ;
static POST_RESPONSE_TYPE_DEF = ;
static PUT_RESPONSE_TYPE_DEF = ;
}
Specify an axios instance for the adapter
To use a specific axios instance:
import { AxiosAdapter, AxiosXHR } from "adapters.ts";
const myAxiosInstance = axios.create();
class SwapiStarship extends AxiosAdapter {
protected static readonly xhr = new AxiosXHR(myAxiosInstance);
static URL_TEMPLATE = "https://swapi.dev/api/starships/{id}";
}
Define new adapter with a http client of your choice
First a class implementing an adapters.ts XHRInterface will be necessary. This class will be used to send actual request and retrieve the payload for validation.
(for reference here is the default axios xhr interface)
import type { XHRInterface, _, RequestMethod } from "adapters.ts";
type MyHTTPClientResponse<T> = {
data: T;
status: number;
};
type MyHTTPClientConfig = {
};
const MyHTTPClientInstance = new MyHTTPClient();
class MyHTTPClientXHR<T = _> implements XHRInterface<MyHTTPClientResponse<T>> {
async sendRequest(params: {
method: RequestMethod;
url: string;
data?: Record<string, any>;
config?: MyHTTPClientConfig;
}): Promise<MyHTTPClientResponse<T>> {
return MyHTTPClientInstance.sendHttpRequest<T>();
}
async extractPayload(response: MyHTTPClientResponse<T>): Promise<T> {
return response.data;
}
}
Provide the XHRInterface class instance to the Adapter:
import { BaseAdapter } from "adapters.ts";
class MyHTTPClientAdapter extends BaseAdapter {
protected static readonly xhr = new MyHTTPClientXHR();
}
The MyHTTPClientAdapter
can be then used in the same way as AxiosAdapter
or FetchAdapter
.