dreqt

Javascript decorator based HTTP request library

Usage no npm install needed!

<script type="module">
  import dreqt from 'https://cdn.skypack.dev/dreqt';
</script>

README

Dreqt

status: active | version: 1.0.2

Dreqt /direct/ is decorator based HTTP request client.

Introduction

Dreqt is JavaScript library inspired by Java. The main idea is allow to make simple and flexible repositories for requests.

Dreqth has bunch of decorators but to be more flexible and generic than normal javascript decorators, Dreqt extends them for parameter binding option.

Installing

npm

$ npm install dreqt --save

cdn

https://unpkg.com/dreqt/Dreqt.js

API

@GET

required

Perform GET request on method that use @GET decorator.

import { GET } from 'dreqt';

class Repository {
  @GET('https://www.website.com/')
  static makeRequest() { }
}

@POST

required

Perform POST request on method that use @POST decorator.

import { POST } from 'dreqt';

class Repository {
  @POST('https://www.website.com/')
  static makeRequest() { }
}

@DELETE

required

Perform DELETE request on method that use @DELETE decorator.

import { DELETE } from 'dreqt';

class Repository {
  @DELETE('https://www.website.com/')
  static makeRequest() { }
}

@PUT

required

Perform PUT request on method that use @PUT decorator.

import { PUT } from 'dreqt';

class Repository {
  @PUT('https://www.website.com/')
  static makeRequest() { }
}

@Headers

optional

Allow to sets own headers for method that use @Headers decorator.

import { GET, Headers } from 'dreqt';

class Repository {
  @Headers({ 'Content-Type': 'application/json' })
  @GET('https://www.website.com/')
  static makeRequest() { }
}

@Data

optional | accepted type: any

Allow to set data for method that use @Data decorator.

import { POST, Data } from 'dreqt';

class Repository {
  @Data('data-text')
  @POST('https://www.website.com/')
  static makeRequest() { }
}

@Timeout

optional | accepted type: number

Allow to set own timeout for method that use @Timeout decorator.

import { Get, Timeout } from 'dreqt';

class Repository {
  @Timeout(1000)
  @GET('https://www.website.com/')
  static makeRequest() { }
}

@WithCredentials

optional | accepted type: boolean

Allow to set credentials for method that use @Timeout decorator.

import { GET, WithCredentials } from 'dreqt';

class Repository {
  @WithCredentials(true)
  @GET('https://www.website.com/')
  static makeRequest() { }
}

@MaxContentLength

optional | accepted type: number

Allow to set max length of the HTTP response content for method that use @MaxContentLength decorator.

import { GET,  MaxContentLength } from 'dreqt';

class Repository {
  @MaxContentLength(500)
  @GET('https://www.website.com/')
  static makeRequest() { }
}

@ResponseType

optional | accepted type: string

Allow to set response type for method that use @ResponseType decorator.

import { GET, ResponseType } from 'dreqt';

class Repository {
  @ResponseType('json')
  @GET('https://www.website.com/')
  static makeRequest() { }
}

@ResponseEncoding

optional | accepted type: string

Allow to set response encoding for method that use @ResponseEncoding decorator.

import { GET, ResponseEncoding } from 'dreqt';

class Repository {
  @ResponseEncoding('utf-8')
  @GET('https://www.website.com/')
  static makeRequest() { }
}

@Auth

optional | accepted type: object | object fields accepted types: string, number

{ 
  username, // string, number
  password // string, nunmber
}

Allow to set basic HTTP auth.

import { Auth } from 'dreqt';

class Repository {
  @Auth({ username: 'user', password: 'pass' })
  @GET('https://www.website.com/')
  static makeRequest() { }
}

@Configuration

optional

Allow to set each field of config in one decorator for method that use @Configuration decorator.

import { GET, Configuration } from 'dreqt';

class Repository {
  @Configuration({
    headers: { 'Content-Type': 'application/json' },
    timeout: 5000,
    maxContentLength: 500,
  })
  @GET('https://www.website.com/')
  static makeRequest() { }
}

@OnError

optional | accepted type: function

Allow to catch and perform action if any error occurs on method that use @OnError decorator.

import { GET, OnError } from 'dreqt';

class Repository {
  @OnError((e) => { console.log(e)}
  @GET('https://www.website.com/')
  static makeRequest() { }
}

DefaultConfig

DefaultConfig provide methods to view and modify default config that Dreqt use to perform requests.

DefaultConfig methods

DefaultConfig.setDefaultConfig(object)

Default used config can be overrided. function setDefaultConfig override only entered fields, each other will be without changes.

import { DefaultConfig } from 'dreqt';

DefaultConfig.setDefaultConfig({
  headers: 'Cache-Control': 'max-age=32000',
  timeout: 1000,
  withCredentials: true,
  maxContentLength: 2000
 })

DefaultConfig.getAsSimpleObject()

Returns all fields of Dreqt configuration in object.

DefaultConfig.getHeaders()

Return default used headers.

DefaultConfig.getTimeout()

Return default used timeout.

DefaultConfig.getWithCredentials()

Return default used withCredentials.

DefaultConfig.getMaxContentLength()

Return default used max response content length.

DefaultConfig.getResponseType()

Return default used response type.

DefaultConfig.getResponseEncoding()

Return default used response encoding.

DefaultConfig.getAuth()

Return default used HTTP auth.

Examples

Perform GET request

import { GET } from 'dreqt';

class Repository {
  @GET('https://www.website.com/')
  static makeRequest() { }
}
Repository.makeRequest();

Perform POST request

import { POST, Data } from 'dreqt';

class Repository {
  @Data('{ id: 5, name: "JaneDoe" }')
  @POST('https://www.website.com/changeUserName')
  static changeUserName() { }
}

Repository.changeUserName();

Error handling

import { GET, OnError } from 'dreqt';

class Repository {
  @OnError((e) => { console.error(e) })
  @GET('https://www.website.com/')
  static errorHandlingTest() { }
}

Repository.errorHandlingTest();

import { GET, OnError } from 'dreqt';

class Repository {
  @OnError('{error}')
  @GET('https://www.website.com/')
  static errorHandlingTest(parametersBinding) { }
}

Repository.errorHandlingTest({
  error: (e) => { console.warn(e); } 
});
Repository.errorHandlingTest({ 
  error: (e) => { console.log(e); } 
});
Repository.errorHandlingTest({ 
  error: (e) => { console.error(e); } 
});

import { GET, OnError } from 'dreqt';

class Repository {
  @OnError('{error}')
  @GET('https://www.website.com/')
  static errorHandlingTest(parametersBinding) { }
}

let catchError = function(e) {
  console.log(e);
}

Repository.errorHandlingTest({
  error:  catchError(e) } 
});

Parameter binding

Dreqt support named parameters.
To set parameter you must close parameter name (combination only of letters and numbers) between two curly brackets, like this {parameter}
To bind parameter you must add parametersBinding argument to your function and fill this argument by object with fields named in same way as parameter closed in colons.

import { GET } from 'dreqt';

class UserRepository {
  @GET('https://www.website.com/user/{id}/article/{article_id}')
  static getUserArticle(parametersBinding) { }
}
UserRepository.getUserArticle({id: 5, article_id: 1});

import { POST, Data } from 'dreqt';

class Repository {
  @Data('{id: {id}, name: "JaneDoe"}')
  @POST('https://www.website.com/')
  static changeUserName(parametersBinding) { }
}

Repository.changeUserName({id: 5});

Header manipulation

You can set custom header for a method using the @Headers decorator.
In case of not using @Headers, request will be used headers from default config.
@Headers argument accepts only string or object.

import { GET, Headers } from 'dreqt';

class UserRepository {
  @Headers({ 'Cache-Control': 'max-age=32000' })
  @GET(url: 'www.database.com/user?id=31')
  static getUser() { }
}

'Ghost' arguments: httpResponse, httpRequest

Method that using @GET, @POST, @DELETE or @PUT decorator has in simple way ability to gather data from requests response and to have in an insight into XMLHttpRequest object.
To get access to these data you can use httpRequest or httpResponse arguments.
httpRequest returns XMLHttpRequest, httpResponse returns object with response data.

Irrespective of order of arguments in method, httpRequest and httpResponse are not respected in the function call and it's not possible to override or interfere with them in calling the function.

import { GET } from 'dreqt';

class UserRepository {
  @GET('https://www.website.com/?userId={id}')
  static getUserById(httpResponse, httpRequest, parametersBinding) {
    console.log(httpResponse);
    console.log(httpRequest);
    console.log(parametersBinding);
  }
}
UserRepository.getUserById({ id: 5 });

Default config

      {
        'headers': {'X-Requested-With': 'XMLHttpRequest'},
        'timeout': 1000,
        'withCredentials': false,
        'maxContentLength': 2000,
        'responseType': 'json',
        'responseEncoding': 'utf8',
        'xsrfCookieName': 'XSRF-TOKEN',
        'xsrfHeaderName': 'X-XSRF-TOKEN',
        'auth': {
          username: null,
          password: null
        },
        'proxy': {
          host: null,
          port: null,
          auth: {
            username: null,
            password: null
          }
        }
      }