Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Networking client for Node.js, React Native & browser web apps
Coolio is an environment-agnostic networking client for Node.js, React Native & browser web apps. The aim of Coolio is to abstract out the technical stuff and let developers query APIs in DRY manner. Usually such approach makes simple things easier while making complex use-cases impossible. Coolio gives users more control over networking, allowing to customize almost every step of it's networking pipeline:
sending and handling requests,
body normalization,
pre and postprocessing.
This is achieved by using interceptors concept and providing pluggable interfaces whenever possible.
Coolio is broken down into several packages, allowing you to pick what's really needed.
Most important yarn
scripts during development:
start
- runs builds for all packages in watch mode
verify
- runs lint & tests
Package | Description |
---|---|
Auth Interceptor with OAuth2 refresh token support for @coolio/http
HTTP networking client
JSON API client
All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.
case-conversion: incorrect name formats are handled gracefully (3d9ce11)
headers: preserve header casing (c767655)
case-conversion: screaming snake case support (1c70407)
headers: explicitly passed nil value removes existing header (e2289bf)
headers & multipart requests: reworked header merging mechanism (b16bfeb)
headers: fixed header merging in fetch requesthandler (d6da36a)
headers: removed deprecated headers options
multipart upload: tested multipart upload on all request handlers (06b353c)
http: bodyparser & bodyserializer support for multipart and formdata (aee40be)
Note: Version bump only for package coolio
Note: Version bump only for package coolio
oauth2interceptor: token-type can be optional (89e9bcd)
Note: Version bump only for package coolio
timeout support: full timeout support for all request handlers (ef5f6d9)
types: properly arranged types for typescript<3.7 (875ca12)
clean: clean should not remove node_modules (9d768e5)
typings: using downlevel-dts to bring back TS<3.7 support (0d6aff9)
build: removed redundant setup file (638993b)
request-handlers: all request handlers are available from bindings (bec0b26)
url-encoding: url string should override query passed in object (b8419f8)
case-conversion: body casing enum has now string names (44c5c43)
http-module: exposed request-handlers separately (d6d4646)
query-string-options: one can configure query string options (cc97360)
redirection-interceptor: built-in support for redirections (b472e13)
redirections: redirection support (cf392d7)
url-encoding: url string has now bigger priority than query passed in object, which results in better composability (parameters from url are always merged into object)
encoding: fix for invalid body encoding issue (c87351c)
http-request-handler: removed duplicated helpers (1622e4b)
http-request-handler: moved to a separate package (569d120)
json-api: added withId functionality to post builder (deb1fc4)
http: fix for headers being overwritten (159e810)
http: body cache fix (98f7375)
http-request-handler: fix for node.js path/query support (d99449c)
http: native request handler for node.js (c0351c5)
auth-interceptor: class-based queue & auth-interceptor (5ec4e40)
auth-interceptor: initial implementation of auth interceptor (8a71e64)
http-interceptors: built-in error interceptor (4c18a23)
http-interceptors: built-in logging interceptor (67d907c)
github actions: fixed invalid path (916714e)
Note: Version bump only for package coolio
action: workspace fix (fd8ab6b)
release: retry npm publish (cd5860f)
token: use regular token (2a3435a)
Note: Version bump only for package coolio
release: combine publishing in one flow (88d9344)
release: separate tag from publish (b19ea2e)
build: build & vulnerability fix (6c3399a)
release: added git credentials (c5f3163)
release: invalid command args (3d87c3d)
workflow: yet another release fix (c4cb917)
workflows: run release with yarn, but use npm underneath (9442197)
build: build & vulnerability fix (6c3399a)
dependencies: dependency update (a78e303)
dependency: dependency fixes (9094ea6)
json-api: new syntax for passing multiple square-bracketed keys to filter in json api (d3f95c1)
@coolio/http
is a simple, yet extendable HTTP client for web apps. It features:
body parsing and serialization, with case-conversion support
raw data (ArrayBuffer)
JSON
URL-encoded
plain text
logger
error handler
redirection interceptor
configurable requestHandler layer, which let's you choose the underlaying mechanism used for HTTP communication
Install @coolio/http
package using npm
or yarn
.
You may create multiple HttpClient
instances, as your application connects to various APIs and each API probably has slightly different conventions. You can initialize a HttpClient and configure it as below:
In the example above, we create HttpClient
instance which will route all paths to api.example.com/v1
address:
if you request /users
, the request will go to api.example.com/v1/users
if you request https://google.com
, the request will go to google.com
, as you specified full URL and baseUrl
is not applied in such case.
You may use the repository pattern to separate API requests from other code. You can use previously defined HttpClient
as below:
After doing the following, you can simply call UserRepository.getProfile()
to receive the Promise returning User
object.
Another way of dealing with repositories is to use class-based approach:
If you happen to use JSON API, you may benefit from using a wrapper library that handles most of it's specs:
multipart ()
extensibility via , with built-ins such as:
Then, our httpClient
uses fetchRequestHandler
to deal with HTTP requests, in order to use Fetch API as request handler. Each requestHandler
in coolio acts as a bridge between natively available mechanisms (such as , or module available in Node.js) and . Such Raw response has to be further processed by bodyParser
. BodyParser and BodySerializer automatically handle most common body types, such as JSON, URL-encoded, plain text, multipart and raw (for binary uploads). As a result we get a nicely processed , which lets us get response body, headers and status code of a response.
You can find all options directly in API docs.
httpClient
allows you to perform requests using all basic http methods. See to check what can be passed there.
See docs for details.
Quite often we need to do something "in-between" while our API requests are running. This is why we have a built-in interceptors mechanism. Interceptors allow us to :
perform actions before request happens,
perform actions after request happens,
retry the request multiple times,
even totally ignore the request and serve content in a different way (i.e. serve content from in-memory cache).
Common use-cases for interceptors:
throw errors if response status code indicates that request failed,
automagically retry request up to X times if it failed,
transparently reauthorize if your access token has been revoked
The concept of interceptors should sound familiar to you if you ever used Angular or OkHttp.
One can add interceptor to HttpClient
using addInterceptor
method. addInterceptor
can be chained and it mutates the httpClient, so you can define a client as below.
coolio offers some basic interceptors, which you probably want to add right away.
coolio supports two ways of creating interceptors. One is a function-based approach and second is a class-based approach. Both ways are correct, just use what fits your use-case best.
Interceptors accept two arguments:
request: HttpFetch
- a function that returns a Promise that performs http request. It allows to queue or delay multiple requests, retry them etc.
options: NormalizedHttpOptions
- options that can be modified before request is made, i.e. you can add Authorization
header in your authInterceptor
.
See the example of error interceptor created as a function:
Interceptor has to return async function that returns response. In other words, it can either:
just return request, which is passed as a first argument to interceptor
create an async function, which performs some operations and then returns response
In the above case, we create such function manually and check the response status code, throwing an error when something goes wrong.
If we'd like to create an interceptor as a class, it would look like that:
By exploiting the fact, that we return a function in our interceptor, we can implement retry mechanism, embed a queue and more. You can see some examples in coolio's auth-interceptor source code.
Networking client for Node.js, React Native & browser web apps
Coolio is an environment-agnostic networking client for Node.js, React Native & browser web apps. The aim of Coolio is to abstract out the technical stuff and let developers query APIs in DRY manner. Usually such approach makes simple things easier while making complex use-cases impossible. Coolio gives users more control over networking, allowing to customize almost every step of it's networking pipeline:
sending and handling requests,
body normalization,
pre and postprocessing.
This is achieved by using interceptors concept and providing pluggable interfaces whenever possible.
Coolio is broken down into several packages, allowing you to pick what's really needed.
Most important yarn
scripts during development:
start
- runs builds for all packages in watch mode
verify
- runs lint & tests
BodyCasing
ContentType
HttpCode
HttpMethod
ParsedBodyCacheState
CFormData
HttpClient
HttpRequestError
HttpResponseError
HttpResponseHeaders
BodyParserOptions
BodySerializerOptions
CFormDataEntryMetadata
CFormDataEntryValue
Endpoint
FetchRequestHandlerOptions
FormDataFromOptions
HttpClientConfig
HttpInterceptorInterface
HttpRequestHandlerOptions
HttpRequestOptions
HttpResponse
HttpResponseOptions
Log
LoggingInterceptorOptions
MockOptions
NormalizedHttpOptions
RawHttpResponse
RedirectionInterceptorOptions
SimpleServer
XhrRequestHandlerOptions
Ƭ BodyParser: function
â–¸ (response
: RawHttpResponse): HttpResponse‹T›
Parameters:
Ƭ BodyParserImplementation: function
â–¸ (rawResponse
: RawHttpResponse): Promise‹any›
Parameters:
Ƭ BodySerializer: function
â–¸ (request
: HttpOptions): NormalizedHttpBody
Parameters:
Ƭ BufferEncoding: "ascii" | "utf8" | "utf-8" | "utf16le" | "ucs2" | "ucs-2" | "base64" | "latin1" | "binary" | "hex"
Ƭ CFormDataValue: string | Blob | Readable
Ƭ CaseConverter: function
â–¸ (object
: any): any
Parameters:
Ƭ ContentTypeMap: Record‹keyof typeof ContentTypeRegex, T›
Ƭ HttpBody: object | TypedArray | string
Ƭ HttpFetch: function
▸ (): Promise‹HttpResponse‹Body››
Ƭ HttpHeaders: Record‹string, string | number | boolean | undefined | null›
Ƭ HttpInterceptor: HttpInterceptorFunction | HttpInterceptorInterface
Ƭ HttpInterceptorFunction: function
â–¸ <Body>(request
: HttpFetch‹Body›, options
: NormalizedHttpOptions): HttpFetch‹Body›
Type parameters:
â–ª Body
Parameters:
Ƭ HttpOptions: Partial‹HttpRequestOptions›
Ƭ HttpRequestHandler: function
â–¸ (requestOptions
: NormalizedHttpOptions): Promise‹RawHttpResponse›
Parameters:
Ƭ MockHttpRequestHandler: HttpRequestHandler & object
Ƭ NormalizedHttpBody: FormData | CFormData | TypedArray | string | undefined
Ƭ PromiseFunction: function
▸ (): Promise‹T›
Ƭ RequestMode: "navigate" | "same-origin" | "no-cors" | "cors"
Const
DEFAULT_REQUEST_TIMEOUT_MS• DEFAULT_REQUEST_TIMEOUT_MS: number = 5 * 60 * 1000
Default request timeout - 5 minutes.
Const
DONE• DONE: 4 = 4
Const
HEADERS_RECEIVED• HEADERS_RECEIVED: 2 = 2
Const
SUPPORTS_BROWSER_FORM_DATA• SUPPORTS_BROWSER_FORM_DATA: boolean = (() => { try { return !({} instanceof FormData); } catch { return false; } })()
• TypedArray: any
Const
symbol• symbol: unique symbol = Symbol('HttpResponseError')
Const
bodyParserâ–¸ bodyParser(__namedParameters
: object): BodyParser‹any›
Parameters:
â–ªDefault value
__namedParameters: object= {}
Returns: BodyParser‹any›
Const
bodySerializerâ–¸ bodySerializer(__namedParameters
: object): BodySerializer
Parameters:
â–ªDefault value
__namedParameters: object= {}
Returns: BodySerializer
Const
cacheParsedBodyâ–¸ cacheParsedBody<T>(parsedBody
: PromiseFunction‹T›): PromiseFunction‹T›
This is not a regular cache! This function is only used across subsequent executions of parsedBody() on a single HttpResponse. To implement cache, make use of interceptors.
Type parameters:
â–ª T
Parameters:
Returns: PromiseFunction‹T›
a promise function returning body, it can be called many times
Const
createAsyncBodyHandlerâ–¸ createAsyncBodyHandler<T>(): object
Type parameters:
â–ª T
Returns: object
call(): Promise‹T›
onBodyFailure(failer
: function): void
onBodyReceived(getter
: function): void
Const
createErrorInterceptorâ–¸ createErrorInterceptor(): HttpInterceptorFunction
Returns: HttpInterceptorFunction
Const
createHttpResponseâ–¸ createHttpResponse(__namedParameters
: object): HttpResponse
Parameters:
â–ª __namedParameters: object
Returns: HttpResponse
Const
createLoggingInterceptorâ–¸ createLoggingInterceptor(__namedParameters
: object): HttpInterceptorFunction
Parameters:
â–ª __namedParameters: object
Returns: HttpInterceptorFunction
Const
createRedirectionInterceptorâ–¸ createRedirectionInterceptor(__namedParameters
: object): HttpInterceptorFunction
Parameters:
â–ªDefault value
__namedParameters: object= {}
Returns: HttpInterceptorFunction
Const
createSimpleServerâ–¸ createSimpleServer(): SimpleServer
Returns: SimpleServer
Const
deepKeyMapâ–¸ deepKeyMap(object
: any, mapper
: function): any
Parameters:
â–ª object: any
â–ª mapper: function
â–¸ (key
: string): string
Parameters:
Returns: any
Const
defaultHeadersâ–¸ defaultHeaders(_host
: string): object
Parameters:
Returns: object
Accept: string = "application/json,application/vnd.api+json"
Content-Type: ContentType = ContentType.JSON
Const
encodeArrayBufferâ–¸ encodeArrayBuffer(data
: TypedArray | string | undefined, encoding
: BufferEncoding): Uint8Array‹›
Parameters:
Returns: Uint8Array‹›
Const
encodeTextâ–¸ encodeText(buffer
: ArrayBuffer, encoding
: string): string
Parameters:
Returns: string
Const
fetchRequestHandlerâ–¸ fetchRequestHandler(fetchRequestHandlerOptions
: FetchRequestHandlerOptions): HttpRequestHandler
Creates a new HttpRequestHandler that uses Fetch API underneath. Does not support timeout property. Abort is possible only after headers were received.
Parameters:
Returns: HttpRequestHandler
Const
getBoundaryFromContentTypeHeaderâ–¸ getBoundaryFromContentTypeHeader(header
: string[]): string
Parameters:
Returns: string
Const
getCaseConverterâ–¸ getCaseConverter(bodyCasing?
: BodyCasing): toCamelCase
Parameters:
Returns: toCamelCase
Const
getEncodingFromHeadersâ–¸ getEncodingFromHeaders(headers
: HttpResponseHeaders | undefined, fallback
: string): string
Parameters:
Returns: string
Const
getFileMetaâ–¸ getFileMeta(value
: Blob | Readable, existingMeta?
: CFormDataEntryMetadata): object | object
Parameters:
Returns: object | object
Const
getHeaderâ–¸ getHeader(headers
: HttpHeaders | undefined, header
: string): string | undefined
Parameters:
Returns: string | undefined
Const
getHostnameâ–¸ getHostname(url
: string): string
Parameters:
Returns: string
Const
handleRequestâ–¸ handleRequest(code
: number, body
: any, contentType
: string): Promise‹HttpResponse›
Parameters:
Returns: Promise‹HttpResponse›
Const
httpRequestHandlerâ–¸ httpRequestHandler(requestHandlerOptions
: HttpRequestHandlerOptions): HttpRequestHandler
Creates a new HttpRequestHandler that uses native Node.js HTTP & HTTPS modules underneath. Does not support mode property.
Parameters:
Returns: HttpRequestHandler
Const
isBlobâ–¸ isBlob(value
: any): value is Blob
Parameters:
Returns: value is Blob
Const
isBrowserFormDataâ–¸ isBrowserFormData(value
: any): value is FormData
Parameters:
Returns: value is FormData
Const
isHttpInterceptorInterfaceâ–¸ isHttpInterceptorInterface(interceptor
: HttpInterceptor): interceptor is HttpInterceptorInterface
Parameters:
Returns: interceptor is HttpInterceptorInterface
Const
isHttpRequestErrorâ–¸ isHttpRequestError(error
: any): error is HttpRequestError
Parameters:
Returns: error is HttpRequestError
Const
isHttpResponseErrorâ–¸ isHttpResponseError(error
: any): error is HttpResponseError
Parameters:
Returns: error is HttpResponseError
Const
mockRequestHandlerâ–¸ mockRequestHandler(mockOptions
: MockOptions): MockHttpRequestHandler
Parameters:
Returns: MockHttpRequestHandler
Const
noConversionâ–¸ noConversion(object
: any): any
Parameters:
Returns: any
Const
parseHeadersâ–¸ parseHeaders(headers
: Headers): Record‹string, string›
Parameters:
Returns: Record‹string, string›
Const
processMultipartBodyâ–¸ processMultipartBody(body
: string, boundary
: string): never
Parameters:
Returns: never
Const
readBlobâ–¸ readBlob(blob
: Blob): Promise‹Buffer›
Parameters:
Returns: Promise‹Buffer›
Const
sanitizeHeadersâ–¸ sanitizeHeaders(...multipleHeaders
: undefined | object[]): Record‹string, string›
Parameters:
Returns: Record‹string, string›
Const
sleepâ–¸ sleep(ms
: number): Promise‹unknown›
Parameters:
Returns: Promise‹unknown›
Const
splitWordsâ–¸ splitWords(text
: string): string[]
Parameters:
Returns: string[]
â–¸ switchContentType<T>(contentType
: string, map
: ContentTypeMap‹T›, defaultResult
: T): T
Type parameters:
â–ª T
Parameters:
Returns: T
â–¸ switchContentType<T>(contentType
: string, map
: ContentTypeMap‹T›): T | undefined
Type parameters:
â–ª T
Parameters:
Returns: T | undefined
Const
toCamelCaseâ–¸ toCamelCase(object
: any): any
Parameters:
Returns: any
Const
toKebabCaseâ–¸ toKebabCase(object
: any): any
Parameters:
Returns: any
Const
toPascalCaseâ–¸ toPascalCase(object
: any): any
Parameters:
Returns: any
Const
toScreamingSnakeCaseâ–¸ toScreamingSnakeCase(object
: any): any
Parameters:
Returns: any
Const
toSnakeCaseâ–¸ toSnakeCase(object
: any): any
Parameters:
Returns: any
Const
toUrlEncodedâ–¸ toUrlEncoded(obj
: object): string
Parameters:
Returns: string
Const
urlCombineâ–¸ urlCombine(sourceUrl
: string, sourceQuery?
: undefined | object, options?
: qs.IStringifyOptions): string
Parameters:
Returns: string
Const
urlDecodeâ–¸ urlDecode<T>(value
: string, options?
: qs.IParseOptions): T
Type parameters:
â–ª T
Parameters:
Returns: T
Const
urlDestructâ–¸ urlDestruct(url
: string, options?
: qs.IParseOptions): object
Parameters:
Returns: object
query: any
url: string
Const
urlEncodeâ–¸ urlEncode(value
: any, options?
: qs.IStringifyOptions): string
Parameters:
Returns: string
Const
useInterceptorâ–¸ useInterceptor(normalizedOptions
: NormalizedHttpOptions): (Anonymous function)
Parameters:
Returns: (Anonymous function)
Const
xhrRequestHandlerâ–¸ xhrRequestHandler(_?
: XhrRequestHandlerOptions): HttpRequestHandler
Parameters:
Returns: HttpRequestHandler
Const
ContentTypeRegex• JSON: RegExp‹› = /^application/(json|.++json)$/
• MULTIPART: RegExp‹› = /^multipart//
• TEXT: RegExp‹› = /^text//
• URL_ENCODED: RegExp‹› = /^application/x-www-form-urlencoded$/
Const
HttpClientHelper• defaultHeaders: defaultHeaders
• getHostname: getHostname
• toUrlEncoded: toUrlEncoded
Const
HttpStatusText• __computed: string = "Network Authentication Required"
Const
Interceptors• createErrorInterceptor: createErrorInterceptor
• createLoggingInterceptor: createLoggingInterceptor
• createRedirectionInterceptor: createRedirectionInterceptor
Base class in Coolio http package, which allows to perform API calls.
â–ª T
Common body shape defined by bodyParser passed in HttpClientConfig.
HttpClient
+ new HttpClient(config
: HttpClientConfig‹T›): HttpClient
Parameters:
Returns: HttpClient
â–¸ addInterceptor(interceptor
: HttpInterceptor): this
Adds an interceptor to the client. Interceptor can be written either as class or as a function, which may mutate request options and post-process response from server. Multiple interceptors can be added to a single HttpClient. They can perform as:
cache
error handler
authorizer
logger
auto-retry
redirection handler
Parameters:
Returns: this
â–¸ delete<Body>(uri
: string, options?
: HttpOptions): Promise‹HttpResponse‹Body››
Performs a DELETE request.
Type parameters:
â–ª Body: T
Parameters:
Returns: Promise‹HttpResponse‹Body››
â–¸ get<Body>(uri
: string, options?
: HttpOptions): Promise‹HttpResponse‹Body››
Performs a GET request.
Type parameters:
â–ª Body: T
Parameters:
Returns: Promise‹HttpResponse‹Body››
â–¸ patch<Body>(uri
: string, options?
: HttpOptions): Promise‹HttpResponse‹Body››
Performs a PATCH request.
Type parameters:
â–ª Body: T
Parameters:
Returns: Promise‹HttpResponse‹Body››
â–¸ post<Body>(uri
: string, options?
: HttpOptions): Promise‹HttpResponse‹Body››
Performs a POST request.
Type parameters:
â–ª Body: T
Parameters:
Returns: Promise‹HttpResponse‹Body››
â–¸ put<Body>(uri
: string, options?
: HttpOptions): Promise‹HttpResponse‹Body››
Performs a PUT request.
Type parameters:
â–ª Body: T
Parameters:
Returns: Promise‹HttpResponse‹Body››
â–¸ remove<Body>(uri
: string, options?
: HttpOptions): Promise‹HttpResponse‹any››
Performs a DELETE request.
deprecated
Use delete instead of remove, since it matches HTTP request method.
Type parameters:
â–ª Body: T
Parameters:
Returns: Promise‹HttpResponse‹any››
â–¸ request<Body>(url
: string, options
: HttpRequestOptions): Promise‹HttpResponse‹Body››
Type parameters:
â–ª Body: T
Parameters:
Returns: Promise‹HttpResponse‹Body››
Create readable "multipart/form-data" streams. Can be used to submit forms and file uploads to other web applications.
CFormData
Parameters:
Static
DEFAULT_CONTENT_TYPEâ–ª DEFAULT_CONTENT_TYPE: string = "application/octet-stream"
Static
LINE_BREAKâ–ª LINE_BREAK: string = " "
Parameters:
Returns: void
â–¸ delete(name
: string): void
Parameters:
Returns: void
â–¸ forEach(callbackfn
: function): void
Parameters:
â–ª callbackfn: function
Parameters:
Returns: void
Parameters:
Parameters:
â–¸ getBoundary(): string
Returns: string
▸ getBuffer(): Promise‹Buffer›
Returns: Promise‹Buffer›
â–¸ getHeaders(): object
Returns: object
content-type: string = 'multipart/form-data; boundary=' + this.getBoundary()
â–¸ has(name
: string): boolean
Parameters:
Returns: boolean
â–¸ pipe(writable
: Writable): void
Parameters:
Returns: void
Parameters:
Returns: void
â–¸ toString(): string
Returns: string
Static
fromParameters:
â–ª data: any
â–ªDefault value
__namedParameters: object= {}
Static
isFormDataâ–¸ isFormData(data
: any): data is FormData | CFormData
Parameters:
Returns: data is FormData | CFormData
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type | Description |
---|---|---|
Name | Type | Default |
---|---|---|
Name | Type |
---|---|
Name | Type | Default |
---|---|---|
Name | Type |
---|---|
Name | Type | Default |
---|---|---|
Name | Type | Default |
---|---|---|
Name | Type | Default |
---|---|---|
Name | Type | Default | Description |
---|---|---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type | Default |
---|---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type | Default |
---|---|---|
Name | Type | Default | Description |
---|---|---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type |
---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type |
---|---|
+ new HttpResponseError(response
: ‹T›, message?
: undefined | string):
Name | Type |
---|
Returns:
Inherited from .
Inherited from .
• response: ‹T›
Inherited from .
Overrides .
• status:
+ new CFormData(data?
: any):
Name | Type |
---|
Returns:
â–¸ append(name
: string, value
: any, meta?
: ): void
Name | Type |
---|
Name | Type |
---|
â–¸ (value
: , key
: string, parent
: ): void
Name | Type |
---|
â–¸ get(name
: string): | null
Name | Type |
---|
Returns: | null
â–¸ getAll(name
: string): []
Name | Type |
---|
Returns: []
Name | Type |
---|
Name | Type |
---|
â–¸ set(name
: string, value
: | Blob, meta?
: ): void
Name | Type |
---|
â–¸ from(data
: any, __namedParameters
: object): FormData |
Name | Type |
---|
Returns: FormData |
Name | Type |
---|
+ new HttpResponseHeaders(headers
: IncomingHttpHeaders | | Headers | string):
Name | Type | Default |
---|
Returns:
Name | Type |
---|
Name | Type |
---|
Interceptor
Purpose
Import
Logger
Logs out requests, responses and errors.
import { createLoggerInterceptor } from '@coolio/http`;
Error Handler
Throws HttpResponseError when response contains 4xx/5xx status code.
import { createErrorInterceptor } from '@coolio/http';
Redirection Handler
Follows redirections, when response contains 301 status code.
import { createRedirectionInterceptor } from '@coolio/http';
Auth
Handles Authorization and reauthenticates automatically when it's needed.
import { createAuthInterceptor } from '@coolio/auth-interceptor';
OAuth
AuthInterceptor following OAuth2 specs. Your job is to provide a storage for tokens only.
import { createOAuth2Interceptor } from '@coolio/auth-interceptor';
Package
Description
Auth Interceptor with OAuth2 refresh token support for @coolio/http
HTTP networking client
JSON API client
response
RawHttpResponse
rawResponse
RawHttpResponse
request
object
any
request
HttpFetch‹Body›
options
NormalizedHttpOptions
requestOptions
NormalizedHttpOptions
bodyCasing
undefined | CAMEL_CASE | SNAKE_CASE | SCREAMING_SNAKE_CASE | PASCAL_CASE | KEBAB_CASE
customCaseConverter
undefined | function
defaultParser
bodyCasing
undefined | CAMEL_CASE | SNAKE_CASE | SCREAMING_SNAKE_CASE | PASCAL_CASE | KEBAB_CASE
parsedBody
PromiseFunction‹T›
a promise function returning parsed body, which in most cases can be called only once
body
undefined | string | Uint8Array‹› | Uint8ClampedArray‹› | Uint16Array‹› | Uint32Array‹› | Int8Array‹› | Int16Array‹› | Int32Array‹› | Float32Array‹› | Float64Array‹›
-
bodyParserOptions
BodyParserOptions
-
headers
undefined | object
-
status
number
-
url
string
""
logger
function
redirectionLimit
number
30
key
string
_host
string
""
data
TypedArray | string | undefined
""
encoding
"utf8"
buffer
ArrayBuffer
-
encoding
string
"utf8"
fetchRequestHandlerOptions
FetchRequestHandlerOptions
{}
default Fetch API options attached to all requests
header
string[]
bodyCasing?
BodyCasing
headers
HttpResponseHeaders | undefined
-
fallback
string
"utf8"
value
Blob | Readable
existingMeta?
CFormDataEntryMetadata
headers
HttpHeaders | undefined
header
string
url
string
code
number
-
body
any
-
contentType
string
ContentType.TEXT
requestHandlerOptions
HttpRequestHandlerOptions
{}
default native options attached to all requests
value
any
value
any
interceptor
error
any
error
any
mockOptions
MockOptions
object
any
headers
Headers
body
string
boundary
string
blob
Blob
...multipleHeaders
undefined | object[]
ms
number
text
string
contentType
string
map
ContentTypeMap‹T›
defaultResult
T
contentType
string
map
ContentTypeMap‹T›
object
any
object
any
object
any
object
any
object
any
obj
object
sourceUrl
string
sourceQuery?
undefined | object
options?
qs.IStringifyOptions
value
string
options?
qs.IParseOptions
url
string
options?
qs.IParseOptions
value
any
options?
qs.IStringifyOptions
normalizedOptions
NormalizedHttpOptions
_?
XhrRequestHandlerOptions
config
HttpClientConfig‹T›
interceptor
Interceptor that will process every request/response in this HttpClient.
uri
string
Address of HTTP endpoint
options?
Additional HttpOptions passed with request
uri
string
Address of HTTP endpoint
options?
Additional HttpOptions passed with request
uri
string
Address of HTTP endpoint
options?
Additional HttpOptions passed with request
uri
string
Address of HTTP endpoint
options?
Additional HttpOptions passed with request
uri
string
Address of HTTP endpoint
options?
Additional HttpOptions passed with request
uri
string
Address of HTTP endpoint
options?
Additional HttpOptions passed with request
url
string
options
| any |
| string |
| string |
| string |
| string |
| Writable |
| undefined | "native" | "custom" |
| any |
| string |
| string |
| any |
Auth interceptor can be plugged in to a HttpClient to ensure passing proper authorization data to all requests and automatically refresh the tokens when they expire. You can configure whether authorization is done by body, header or query param, you can define your own refresh mechanism or use some ready-made, commonly used options.
Add the Auth Interceptor package, assuming that you already have @coolio/http
installed:
Declare httpClient
as described in @coolio/http's README.md and then use createAuthInterceptor
, passing all parameters required by options
object. authInterceptor
itself may also make it's own calls (via reauthorize
function), so you may need to create another HttpClient
, which won't interfere with your basic HttpClient
's interceptors. See the Usage section for complete example.
Now each request directed to my-domain.org
has a proper Authorization
header. In case of 401
response, all requests are paused and token refresh happens. When token is fresh, all requests are resumed. The whole process is transparent and doesn't affect calls.
If you're using OAuth2 authentication mechanisms, you can use an interceptor pre-made specifically for that case. See an example below:
|
| undefined | string |
| string |
| any |
|
|
| string |
|
| string |
|
|
| {} |
AuthError
AuthInterceptor
InMemoryAuthStorage
SimpleQueue
AuthInterceptorOptions
AuthStorage
OAuth2InterceptorOptions
OAuth2TokenResponse
Ƭ Promisable: T | Promise‹T›
Ƭ QueueItem: object
fail(): function
(reason
: any): void
run(): function
(): Promise‹void›
Const
createAuthInterceptorâ–¸ createAuthInterceptor(options
: AuthInterceptorOptions): AuthInterceptor‹›
Parameters:
Returns: AuthInterceptor‹›
Const
createOAuth2Interceptorâ–¸ createOAuth2Interceptor(__namedParameters
: object): AuthInterceptor‹›
Parameters:
â–ª __namedParameters: object
Returns: AuthInterceptor‹›
Const
hasUnauthorizedResponseCodeâ–¸ hasUnauthorizedResponseCode(response
: HttpResponse): boolean
Parameters:
Returns: boolean
Const
isUnauthorizedErrorâ–¸ isUnauthorizedError(error
: any): boolean
Parameters:
Returns: boolean
SortOrder
CreationalRequestBuilder
JsonApiClient
JsonApiManySender
JsonApiOneSender
JsonApiRequestData
JsonApiSender
JsonListResponse
JsonResponse
RequestBuilder
Attributes
Data
IncludedGroup
ListMetaData
RawListResponse
RawResponse
RequestBuilderOptions
Ƭ AnyData: Data‹any, any›
Ƭ AttributesOf: D extends object ? D["attributes"] : EmptyRecord
Ƭ EmptyRecord: object
[ key: string]: never
Ƭ IncludedGroups: object
Ƭ IncludedGroupsSchema: Record‹string, IncludedGroup›
Ƭ IncludedRelationships: D[]
Ƭ MergedData:
This sophisticated type allows to correctly infer nicely formatted data from JSON API format. id
, type
, attributes
and relationships
suddenly become a single, combined object with easy access to it. Same is applied to arrays.
Ƭ MergedIncludedGroups: object
Ƭ OptionalRels: Relationships | undefined
Ƭ RawRelationship: object
data: T
links? : undefined | object
related? : undefined | string
Ƭ Relationship: RawRelationship‹RelationshipData›
Ƭ RelationshipArray: RawRelationship‹RelationshipData[]›
Ƭ RelationshipData: object
id: string
type: Type
Ƭ RelationshipType: RelationshipData‹Type› | RelationshipData‹Type›[]
Ƭ Relationships: Record‹string, RawRelationship‹RelationshipType› | undefined›
Ƭ RelationshipsOf: D extends object ? D["relationships"] : EmptyRecord
Ƭ ResolvedRelationship: RawRelationship‹D›
Ƭ ResolvedRelationshipArray: RawRelationship‹D[]›
Ƭ ResolvedRelationships: Record‹string, ResolvedRelationship | ResolvedRelationshipArray | undefined›
Ƭ UnresolvedRelationships: Record‹string, Relationship | RelationshipArray›
Const
DEFAULT_RESOURCE_LIMIT• DEFAULT_RESOURCE_LIMIT: 10 = 10
Const
findIncludedRelationshipâ–¸ findIncludedRelationship(relationship
: RelationshipData, included
: IncludedRelationships): AnyData | undefined
Parameters:
Returns: AnyData | undefined
Const
includedGroupâ–¸ includedGroup<D>(type
: string): IncludedGroup‹D›
Type parameters:
â–ª D: AnyData
Parameters:
Returns: IncludedGroup‹D›
Const
isDataâ–¸ isData<D>(data
: RelationshipData | D): data is D
Type parameters:
â–ª D: AnyData
Parameters:
Returns: data is D
Const
mergeElementDataâ–¸ mergeElementData<D>(data
: D): MergedData‹D›
Type parameters:
â–ª D: AnyData
Parameters:
Returns: MergedData‹D›
â–¸ resolveRelationships<D>(data
: D, included
: IncludedRelationships): D
Type parameters:
Parameters:
Returns: D
â–¸ resolveRelationships(data
: RelationshipData[], included
: IncludedRelationships): object | Data‹any, any›[]
Parameters:
Returns: object | Data‹any, any›[]
â–¸ resolveRelationships(data
: RelationshipData, included
: IncludedRelationships): AnyData | RelationshipData
Parameters:
Returns: AnyData | RelationshipData
Const
Headers• Accept: ContentType = ContentType.VND_JSON
• Content-Type: ContentType = ContentType.VND_JSON
‹T›
| Blob
IncomingHttpHeaders | | Headers | string
+ new HttpRequestError(options
: , message?
: undefined | string):
Name | Type |
---|
Returns:
Inherited from .
Inherited from .
• options:
Inherited from .
Overrides .
Name
Type
options
AuthInterceptorOptions
Name
Type
authStorage
AuthStorage‹OAuth2TokenResponse›
canAuthorize
function
oauth
object
onAuthorizationFailure
function
Name
Type
response
HttpResponse
Name
Type
error
any
Name
Type
relationship
included
Name
Type
type
string
Name
Type
data
RelationshipData | D
Name
Type
data
D
Name
Type
data
D
included
Name
Type
data
included
Name
Type
data
included
|
| undefined | string |
JSON API Client Wrapper
Add the JSON API package, assuming that you already have @coolio/http
installed:
Declare httpClient
as described in @coolio/http's README.md and then build JSON API Client:
Make sure that httpClient uses standard bodyParser
or a parser that returns complete body of server's response (an object including at least data
property).
An instance of JsonApiClient
exposes a collection of get()
, getList()
, post()
, remove()
, put()
and patch()
methods. Each method returns a request builder. For example:
UsersRepository.getUsers()
method presented above returns a Promise<JsonListResponse<UserAttributes, UserRelationships>>
. @coolio/json-api
merges attributes and relationships automatically.