#Fetchy
The Fetchy class represent an handy and configurable helper that allows to easily interact with remote resources.
Any instance can be configured in many different aspects while enforcing use of correct configuration.
Leveraging its functionalities it's easy to generate pre-configured instances of any given remote resource, and easily query them with cool features like: automatic error handling, caching, timeouts, etc.
Using npm:
$ npm i @devicious/fetchy //Import the Library
import Fetchy from "@devicious/fetchy"
//Define and configure a new instance of a Fetchy Class
const Authors = new Fetchy("/api/v1/authors")
.method('POST')
.cache(true)
.id('articles')
.expiry(1);
//Further edit the configuration and fire the request.
Authors
.data({
parameter1: 'value1',
parameter2: 'value2'
})
.then((results) => {
console.log(results);
});
//Execute another call with different parameters (caching won't affect the results since the payload has changed)
Authors
.data({
parameter4: 123,
parameter6: false
})
.then((results) => {
console.log(results);
})
.catch((error) => {
console.log(error);
});- attachSelf
- cache
- call
- catch
- clearCache
- clone
- credentials
- data
- do
- expiry
- finally
- format
- formatResponse
- getCacheHash
- headers
- id
- isCached
- isInQueue
- method
- mode
- override
- refreshCacheStorage
- retrieveCached
- retry
- setQueue
- storeCached
- then
- timeout
- validator
• new Fetchy(url)
const Resource = new Fetchy("/api/v1/:endpoint");
Resource.then((data) => {
//...
});| Name | Type |
|---|---|
url |
string |
• Private writable: boolean = true
The properties of a Fetchy instance are mutable up until the first fetch.
From that moment only the payload data can be mutated, in order to prevent consistency issues.
• Private Readonly cacheQueueRetries: 40
Internal use only.
internal
• Private Readonly cacheQueueUID: "_cacheResponseQueue"
Internal use only.
internal
• Private cacheStorage: Object = {}
This variable handles the internal caching storage.
internal
• Private Readonly cacheUID: "_cacheResponseData"
Internal use only.
internal
• Private config: FetchyConfig
This variable represents the internal state of a Fetchy instance.
It mutates while you configure your instance, and it's inherited from its child.
internal
▸ Private attachSelf(response): any
internal
| Name | Type |
|---|---|
response |
any |
any
▸ cache(enable): Fetchy
Enable or disable automatic caching for the current Fetchy instance.
Caching is performed automatically when enabled based on the current set of parameters, and automatically handling configuration changes.
Any change in the configuration or data payload will generate new calls instead of fetching from the cache.
cache
| Name | Type | Description |
|---|---|---|
enable |
boolean |
true | false |
the Fetchy class instance
▸ Private call(): Promise<Response>
internal
Promise<Response>
▸ catch(fn): any
Triggers the data fetch and returns the final payload.
After this method is invoked is no longer possible to change this instance configuration without cloning it.
request
| Name | Type | Description |
|---|---|---|
fn |
Function |
A callback function that is invoked with the result of the fetch in case of error |
any
a mutated version of Fetchy class instance that inherits all the properties of a Promise.
▸ clearCache(id?): void
Allows to clear the cached entries of a specific id or in general.
cache
| Name | Type | Description |
|---|---|---|
id? |
string |
The id of the cached entity. *optional |
void
▸ clone(): Fetchy
Clones the current instance into a new one, allowing for configuration changes without affecting the original instance.
utility
a new clone of Fetchy class instance that inherits all previous configurations.
▸ credentials(credentials): Fetchy
Sets the credential mode for the current Fetch instance.
request
| Name | Type | Description |
|---|---|---|
credentials |
string |
Allowed values: 'omit', 'same-origin', 'include' |
the Fetchy class instance
▸ data(data): Fetchy
Allows to set request payload.
request
| Name | Type | Description |
|---|---|---|
data |
any |
Allowed formats: Object, Array, String. |
a new clone of Fetchy class instance that inherits all previous configurations.
▸ Private do(): any
internal
any
▸ expiry(minutes): Fetchy
Sets a time in minutes after which any cached request will be discarded and substituted with a fresh data fetch.
cache
| Name | Type | Description |
|---|---|---|
minutes |
number |
Timing expressed in minutes |
the Fetchy class instance
▸ finally(fn): any
Triggers the data fetch and returns the final payload.
After this method is invoked is no longer possible to change this instance configuration without cloning it.
request
| Name | Type | Description |
|---|---|---|
fn |
Function |
A callback function that is invoked with the result of the fetch in either case |
any
a mutated version of Fetchy class instance that inherits all the properties of a Promise.
▸ format(format): Fetchy
Allows to set fetch expected response format
request
| Name | Type | Description |
|---|---|---|
format |
string |
Allowed values: 'json', 'text', 'blob' |
the Fetchy class instance
▸ Private formatResponse(metaResponse): any
internal
| Name | Type |
|---|---|
metaResponse |
any |
any
▸ Private getCacheHash(): string
internal
string
▸ headers(headers): Fetchy
Allows to set headers for the fetch call.
request
| Name | Type | Description |
|---|---|---|
headers |
any |
Allowed values Array, Object |
the Fetchy class instance
▸ id(id): Fetchy
Sets a unique id for the current Fetch instance, allowing more clear and debug friendly caching
cache
| Name | Type | Description |
|---|---|---|
id |
string |
Allowed values: Any unique string |
the Fetchy class instance
▸ Private isCached(): boolean
internal
boolean
▸ Private isInQueue(): boolean
internal
boolean
▸ method(method): Fetchy
Allows to set a method for the fetch call.
request
| Name | Type | Description |
|---|---|---|
method |
string |
Allowed values: 'GET', 'POST', 'PATCH', 'PUT', 'DELETE', 'OPTIONS' |
the Fetchy class instance
▸ mode(mode): Fetchy
Sets a mode for the current Fetch instance to handle CORS issues
request
| Name | Type | Description |
|---|---|---|
mode |
string |
Allowed values: 'cors', 'same-origin', 'no-cors' |
the Fetchy class instance
▸ override(config): Fetchy
Override the current configuration of the Fetchy instance without format restrictions, should not be used.
internal
| Name | Type |
|---|---|
config |
any |
a new clone of Fetchy class instance that inherits all previous configurations.
▸ Private refreshCacheStorage(): void
internal
void
▸ Private retrieveCached(): Promise<unknown>
internal
Promise<unknown>
▸ retry(times, delayMs?): Fetchy
Allows to set automatic retries in case of fetch failure.
errorhandling
| Name | Type | Default value | Description |
|---|---|---|---|
times |
number |
undefined |
Number of times to retry before considering failed the request |
delayMs |
number |
0 |
Time to wait between each try, expressed in ms. |
the Fetchy class instance
▸ Private setQueue(): void
internal
void
▸ Private storeCached(response): void
internal
| Name | Type |
|---|---|
response |
any |
void
▸ then(fn): any
Triggers the data fetch and returns the final payload.
After this method is invoked is no longer possible to change this instance configuration without cloning it.
request
| Name | Type | Description |
|---|---|---|
fn |
Function |
A callback function that is invoked with the result of the fetch in case of success |
any
a mutated version of Fetchy class instance that inherits all the properties of a Promise.
▸ timeout(seconds): Fetchy
Allows to set fetch timeout in seconds.
errorhandling
| Name | Type | Description |
|---|---|---|
seconds |
number |
Must be a value equal or greater than 1 |
the Fetchy class instance
▸ validator(fn): Fetchy
Sets a validator function to allow or forbid caching of any request coming from this instance. The cache is common among all Fetchy instances
Defaults to Ensure that the response is not empty and with status code 200.
cache
| Name | Type | Description |
|---|---|---|
fn |
any |
Allowed values: 'cors', 'same-origin', 'no-cors' |
the Fetchy class instance
Example validator function:
const Helper = new Fetchy("/api/v1/:endpoint")
.cache(true) //Caching must be enabled for validator function to take any effect.
.validator((response) => {
return response && response.header.status === "OK";
});