src/index.js
43 |
import validate from './validate'
44 | import { addQueryParams, mixinDynamicSegmentsValues } from './utils/url'
45 |
46 | const identity = x => x
47 |
48 | const defaultParams = {
49 | executor: null,
50 | url: null,
51 | method: null,
52 | headers: [],
53 | body: null,
54 | responseType: null,
55 | dynamicSegments: [],
56 | queryParams: [],
57 | bodyProcessor: identity,
58 | responseProcessor: identity
59 | }
60 |
61 | class Internals {
62 | constructor (params) {
63 | Object.entries(params)
64 | .map(([key, value]) =>
65 | Object.defineProperty(this, key, {
66 | get: () => value,
67 | enumerable: true,
68 | configurable: true
69 | }))
70 | }
71 | }
72 |
73 | /**
74 | * @typedef {[key: string, value: string]} Tuple
75 | */
76 |
77 | /**
78 | * @typedef {Object} HttpRequestParams
79 | * @property {string} url resource url
80 | * @property {string} method HTTP method,
81 | * @property {Tuple[]} headers array of HTTP headers key-value pairs
82 | * @property {Object} body request payload
83 | * @property {string} responseType response type
84 | * @property {Tuple[]} dynamicSegments key-value array of replacements for the provided url
85 | * @property {Tuple[]} queryParams key-value array of url params
86 | * @property {function(x: Object): Object} bodyProcessor map body function
87 | * @property {function(x: Object): Object} responseProcessor map response function
88 | * @property {function(url: string, method: string, headers: string[], responseType: string, body: Object): Promise} executor performs HTTP request and returns Promise,
89 | */
90 |
91 | // executor: function(url: string, method: string, headers: string[], responseType: string, body: Object): Promise,
92 | // bodyProcessor: function(x: Object): Object, responseProcessor: function(x: Object): Object
93 |
94 | /**
95 | * Http request object.
96 | * Expose chainable API
97 | */
98 | export default class Http {
99 |
100 | /**
101 | * @param {HttpRequestParams} params - HTTP request params
102 | */
103 | constructor (params = defaultParams) {
104 | const internals = new Internals(params)
105 | this.internals = () => internals
106 | }
107 |
108 | /**
109 | * Set the middleware that will perform the request
110 | * @param {function(url: string, method: string, headers: string[], responseType: string, body: Object): Promise} executor -
111 | * function which performs the request asynchroniously and returns Promise back
112 | * @returns {Object} Http object
113 | */
114 | executor (executor) {
115 | return new Http(Object.assign({}, this.internals(), { executor }))
116 | }
117 |
118 | /**
119 | * Adds URL information to HTTP request model
120 | * @param {string} url - URL
121 | * @returns {Object} Http object
122 | */
123 | url (url) {
124 | return new Http(Object.assign({}, this.internals(), { url }))
125 | }
126 |
127 | /**
128 | * Adds HTTP method information to request model
129 | * @param {string} method - HTTP method
130 | * @returns {Object} Http object
131 | */
132 | method (method) {
133 | return new Http(Object.assign({}, this.internals(), { method }))
134 | }
135 |
136 | /**
137 | * Adds header to request model
138 | * @param {string} header - valid header key
139 | * @param {string} value - valid header value
140 | * @returns {Object} Http object
141 | */
142 | header (header, value) {
143 | const headers = this.internals().headers.concat([[header, value]])
144 | return new Http(Object.assign({}, this.internals(), { headers }))
145 | }
146 |
147 | /**
148 | * Adds body to request model
149 | * @param {Object} body - request payload
150 | * @returns {Object} Http object
151 | */
152 | body (body) {
153 | return new Http(Object.assign({}, this.internals(), { body }))
154 | }
155 |
156 | /**
157 | * Sets response content type
158 | * Proper values could be obtained form XmlHttpRequest specification
159 | * https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest#Properties
160 | * @param {string} responseType - Proper values could be obtained form
161 | * XmlHttpRequest specification
162 | * https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest#Properties
163 | * @returns {Object} Http object
164 | */
165 | responseType (responseType) {
166 | return new Http(Object.assign({}, this.internals(), { responseType }))
167 | }
168 |
169 | /**
170 | * Adds dynamic segment value
171 | * @param {string} segment - segment key
172 | * @param {string} value - segment value
173 | * @returns {Object} Http object
174 | */
175 | segment (segment, value) {
176 | const dynamicSegments
177 | = this.internals().dynamicSegments.concat([[segment, value]])
178 | return new Http(Object.assign({}, this.internals(), { dynamicSegments }))
179 | }
180 |
181 | /**
182 | * Adds query string param
183 | * @param {string} name - param key
184 | * @param {string} value - param value
185 | * @returns {Object} Http object
186 | */
187 | query (name, value) {
188 | const queryParams = this.internals().queryParams.concat([[name, value]])
189 | return new Http(Object.assign({}, this.internals(), { queryParams }))
190 | }
191 |
192 | /**
193 | * Sets the function which gets the body object as a parameter
194 | * which result would be used as a request body
195 | * @param {func} bodyProcessor - f(x) => valid_http_body
196 | * @returns {Object} Http object
197 | */
198 | bodyProcessor (bodyProcessor) {
199 | return new Http(Object.assign({}, this.internals(), { bodyProcessor }))
200 | }
201 |
202 | /**
203 | * Sets the function which gets the response and produces another value
204 | * Useful for default HTTP error handling
205 | *
206 | * @example
207 | * response => {
208 | * switch(response.code) {
209 | * case "404":
210 | * return { message: 'Resource not found' }
211 | * }
212 | *}
213 | *
214 | * @param {func} responseProcessor - f(x) => y
215 | * @returns {Object} Http object
216 | */
217 | responseProcessor (responseProcessor) {
218 | return new Http(Object.assign({}, this.internals(), { responseProcessor }))
219 | }
220 |
221 | /**
222 | * Executes HTTP request
223 | * @returns {Object} - Promise
224 | */
225 | exec () {
226 | const {
227 | url, method, headers, responseType, dynamicSegments, queryParams, body,
228 | bodyProcessor, responseProcessor, executor
229 | } = this.internals()
230 | if (!executor) {
231 | throw new Error('executor was not set')
232 | }
233 | const errors = validate(url, method, headers, responseType)
234 | if (errors.length !== 0)
235 | throw new Error(errors.join('\n'))
236 | const urlWithDynamicSegments
237 | = mixinDynamicSegmentsValues(url, dynamicSegments)
238 | const fullUrl = addQueryParams(urlWithDynamicSegments, queryParams)
239 | return executor(
240 | fullUrl, method, headers, responseType, bodyProcessor(body)
241 | ).then(responseProcessor)
242 | }
243 | }
244 |
245 |
246 |
src/utils/url.js
43 |
/**
44 | * @ignore
45 | * Mixins dynamic segments replacing the `:segment_name` parts with provide
46 | * values
47 | * @param {String} url – URL
48 | * @param {Object} dynamicSegments – dynamic segments
49 | * @returns {String} – URL
50 | */
51 | export function mixinDynamicSegmentsValues (url, dynamicSegments) {
52 | return dynamicSegments.reduce((aggr, [key, value]) =>
53 | aggr.replace(`:${key}`, value), url)
54 | }
55 |
56 | /**
57 | * @ignore
58 | * Adds query params string to url
59 | * @param {string} url – URL
60 | * @param {Array} queryParams – query params
61 | * @returns {String} – URL
62 | */
63 | export function addQueryParams (url, queryParams) {
64 | const chanks = queryParams.map(([key, value]) => `${key}=${value}`)
65 | return url + (chanks.length !== 0 ? '?' + chanks.join('&') : '')
66 | }
67 |
68 |
69 |
src/validate.js
43 |
import option from 'option'
44 |
45 | const supportedMethods = ['GET', 'POST', 'PUT', 'DELETE']
46 | const validTypes = [null, '', 'arraybuffer', 'blob', 'document', 'text', 'json']
47 |
48 | /**
49 | * Validate HTTP method
50 | * @param {String} method – HTTP method
51 | * @return {String} error
52 | */
53 | function validateMethod (method) {
54 | if (!method) {
55 | return option.some('HTTP method is not specified')
56 | }
57 | if (typeof method !== 'string') {
58 | return option.some('HTTP method should be type of string')
59 | }
60 | if (supportedMethods.indexOf(method.toUpperCase()) < 0) {
61 | return option.some(`Http method ${method} is not supported`)
62 | }
63 | return option.none
64 | }
65 |
66 | /**
67 | * Basicly validate url
68 | * @param {String} url – URL
69 | * @return {String} error
70 | */
71 | function validateUrl (url) {
72 | if (!url) {
73 | return option.some('Url is not specified')
74 | }
75 | if (typeof url !== 'string') {
76 | return option.some('Url should be type of string')
77 | }
78 | return option.none
79 | }
80 |
81 | /**
82 | * Validate header to all parts be strings
83 | * @param {String} key – Header key
84 | * @param {String} value – Header value
85 | * @return {String} error
86 | */
87 | function validateHeader (key, value) {
88 | if (typeof key !== 'string' || typeof value !== 'string')
89 | return option.some(`Parts of header ${key}:${value} must be strings`)
90 | return option.none
91 | }
92 |
93 | /**
94 | * Validate headers
95 | * @param {Object} headers – headers
96 | * @return {Array} error
97 | */
98 | function validateHeaders (headers) {
99 | const aggr = []
100 | for (let [key, value] of headers)
101 | aggr.push(validateHeader(key, value))
102 | return aggr
103 | }
104 |
105 | /**
106 | * Validates response type
107 | * @param {string} type - response type
108 | * @return {String} error
109 | */
110 | function validateResponseType (type) {
111 | if (validTypes.indexOf(type) < 0)
112 | return option.some(`Response content type ${type} is not supported`)
113 | return option.none
114 | }
115 |
116 | /**
117 | * @ignore
118 | * Validate HTTP request model
119 | * @param {String} url – url
120 | * @param {String} method – HTTP method
121 | * @param {Map} headers – HTTP headers
122 | * @param {String} responseType – response type
123 | * @return {Array} array of errors
124 | */
125 | function validate (url, method, headers, responseType) {
126 | return [validateUrl(url),
127 | validateMethod(method),
128 | validateResponseType(responseType)]
129 | .concat(validateHeaders(headers)).filter(_ => _.isSome()).map(_ => _.value())
130 | }
131 |
132 | export default validate
133 |
134 |
135 |
Immutable-http
43 |
44 | 
45 |
Http client with pretty simple chaining API
46 |
Docs
47 |
Usage
48 |
import executor from 'third-party-executor'
49 |
50 | var result = new Http().url('http://any_api.com/:id')
51 | .executor(executor)
52 | .method('GET')
53 | .header('Content-Type','application/json')
54 | .body({some:data})
55 | .responseType('json')
56 | .segment('id',123)
57 | .query('filter','some_filter') // Adds query section for the url like '?filter=some_filter'
58 | .exec(); // returns Promise
59 |
60 |
executor is just a function with signature
61 |
f(url: String, method: String, headers:Array[Tuple[String, String]], responseType: String, body: Any): Promise
62 |
63 |
It allows you to have your own favorite HTTP library under the hood and be able to test your code with mocked executor without any hacks.
64 | Executor implementation example
65 |
Build
66 |
npm run dist
67 |
Tests
68 |
Run
69 |
npm test
70 |
71 |
26 |
27 | 