dk-request
v3.4.5
Published
Request utility with validations based on Axios & ts-interface-checker
Downloads
188
Readme
Request utility with validations based on Axios & ts-interface-checker
[!WARNING]
It's fine if you use this library from NPM package with a static versioning in case you want it for some pet-project or to test it's capabilities.But for production use it's strongly recommended to create a fork, because I do not write Changelogs and may break / add some functionality without notice.
Features
- validates request and response by
ts-interface-checker
. Checkers could be created using dk-file-generator - omits extraneous params from response using dk-checker-remove-extraneous
- supports mocks
- supports file downloads if response type is
blob
with customizable file name - supports FormData requests
- supports
url
as function - supports custom headers
- works in Node.js
- request params starting with
omit_
are used in inurl
creation but omitted in body
Installation
Add dk-request
to package.json and install.
Usage
import { AxiosError } from 'axios';
import { request, errors } from 'dk-request';
type TypeRequest = {
id: string;
}
type TypeResponse = {
data: string;
}
// possibly auto-generated
const validators = t.createCheckers({
TypeRequest: t.iface([], { id: 'string' }),
TypeResponse: t.iface([], { data: 'string' }),
});
request({
url: 'https://google.com/api/get-items',
// url: (requestParams) => `https://google.com/api/get-items/${requestParams.id}`,
apiName: 'getItems',
requestParams: { id: 'id' } as TypeRequest,
validatorRequest: validators.TypeRequest,
validatorResponse: validators.TypeResponse,
}).then((response: TypeResponse) => {
// response is validated and cleared, put it in store or use as you need
successHandler(response);
}).catch((error: Error | AxiosError) => {
// if it's validation error then
// error.name === errors.VALIDATION
// error.message smth. like
// 'validateRequest: request.id is missing for "getItems"'
// 'validateResponse: response.data is not a string for "getItems"'
errorHandler(error);
});
Params
url
- string | ((request: any) => string)
- full url
apiName
- string
- just for logging
requestParams
- Record<string, any> & { formData?: any; downloadAsFile?: boolean }
If you need to send FormData include it in formData
. Other params will not be sent, but
could still be used in url
function.
If you need to download file passed as blob
by backend use downloadAsFile: true
, this
way response validation will be omitted.
mock
(optional) - TypeResponse
, there will be no actual request to API, but validations are
applied
method
(optional, default POST
) - 'GET' | 'POST' | 'PUT' | 'DELETE'
headers
(optional) - Record<string, any>
extraneousLogger
(optional) - logger for dk-checker-remove-extraneous
validatorRequest
(optional) - Checker
validatorResponse
(optional) - Checker
disableCredentials
(optional) - boolean
- restrict or allow sending of cookies along with request
omitResponseValidation
(optional) - boolean
- restrict or allow response validation
afterRequestInterceptor
(optional) - (response: AxiosResponse) => Promise<void>
- a method for
performing some manipulations with response, like checking response.headers
(ex. server sends
JWT token in headers)
afterRequestInterceptor: (axiosResponse) => {
const newToken = axiosResponse.headers.authorization;
if (newToken) setTokenToStore(newToken);
return Promise.resolve();
}
downloadFileNameGetter
(optional) - (response: AxiosResponse) => string
- a method for
defining custom downloaded file name, ex.
downloadFileNameGetter: (axiosResponse) => {
return (
axiosResponse.headers['content-disposition']?.split('filename=')?.[1]?.replaceAll('"', '') ||
'result.csv'
);
}
For access to response headers like
content-disposition
don't forgetexpose-headers
header in server response