UNPKG

4.57 kBMarkdownView Raw
1# ![Popsicle](https://cdn.rawgit.com/serviejs/popsicle/master/logo.svg)
2
3[![NPM version](https://img.shields.io/npm/v/popsicle.svg?style=flat)](https://npmjs.org/package/popsicle)
4[![NPM downloads](https://img.shields.io/npm/dm/popsicle.svg?style=flat)](https://npmjs.org/package/popsicle)
5[![Build status](https://img.shields.io/travis/serviejs/popsicle.svg?style=flat)](https://travis-ci.org/serviejs/popsicle)
6[![Test coverage](https://img.shields.io/coveralls/serviejs/popsicle.svg?style=flat)](https://coveralls.io/r/serviejs/popsicle?branch=master)
7[![Bundle size](https://img.shields.io/bundlephobia/minzip/popsicle.svg)](https://bundlephobia.com/result?p=popsicle)
8
9> Advanced HTTP requests in node.js and browsers, using [Servie](https://github.com/serviejs/servie).
10
11## Installation
12
13```
14npm install popsicle --save
15```
16
17## Usage
18
19```js
20import { transport, request } from 'popsicle'
21
22const req = request('http://example.com') // Creates a `Request` instance.
23const res = await transport()(req) // Transports `Request` and returns `Response` instance.
24```
25
26Thin wrapper to transport [Servie](https://github.com/serviejs/servie) HTTP request interfaces.
27
28**P.S.** The default export from `popsicle` is `universal.js`. In TypeScript, this can cause trouble with types. Use specific imports such as `popsicle/dist/{browser,node,universal}` instead, depending on preference.
29
30### Node.js Normalization
31
32Normalizes some behavior that happens automatically in browsers (each normalization can be disabled).
33
34* Default `User-Agent` insertion
35* Default unzip behaviour of `gzip` and `deflate` encoding
36* Follows HTTP redirects
37
38### Built-in Transports
39
40#### HTTP (node.js)
41
42* **unzip: boolean** Automatically unzip response bodies (default: `true`)
43* **follow: boolean** Automatically follow HTTP redirects (default: `true`)
44* **jar: CookieJar** An instance of a cookie jar (`jar()` from `node.js` import)
45* **maxRedirects: number** Override the number of redirects allowed (default: `5`)
46* **confirmRedirect: Function** Validate `307` and `308` redirects (default: `() => false`)
47* **rejectUnauthorized: boolean** Reject invalid SSL certificates (default: `true`)
48* **agent: http.Agent** Custom `http.request` agent
49* **ca: string | Buffer** A string, `Buffer` or array of strings or `Buffers` of trusted certificates in PEM format
50* **key: string | Buffer** Private key to use for SSL
51* **cert: string | Buffer** Public x509 certificate to use
52* **secureProtocol: string** Optional SSL method to use
53
54#### XHR (browsers)
55
56* **type: XMLHttpRequestResponseType** Handle the XHR response (default: `text`)
57* **withCredentials: boolean** Send cookies with CORS requests (default: `false`)
58* **overrideMimeType: string** Override the XHR response MIME type
59
60#### Errors
61
62Transports can return an error. Errors have a `request` property set to the request object and a `code` string. The built-in codes are documented below:
63
64* **EUNAVAILABLE** Unable to connect to the remote URL
65* **EINVALID** Request URL is invalid (browsers)
66* **EMAXREDIRECTS** Maximum number of redirects exceeded (node.js)
67* **EBLOCKED** The request was blocked (HTTPS -> HTTP) (browsers)
68* **ECSP** Request violates the documents Content Security Policy (browsers)
69* **ETYPE** Invalid transport type (browsers)
70
71### Plugins
72
73_Coming back soon._
74
75### Helpful Utilities
76
77* [`throat`](https://github.com/ForbesLindesay/throat) - Throttle promise-based functions with concurrency support
78* [`is-browser`](https://github.com/ForbesLindesay/is-browser) - Check if your in a browser environment (E.g. Browserify, Webpack)
79* [`parse-link-header`](https://github.com/thlorenz/parse-link-header) - Handy for parsing HTTP link headers
80
81### Creating Plugins
82
83See [Throwback](https://github.com/serviejs/throwback#usage) for more information:
84
85```ts
86type Plugin = (req: Request, next: (req?: Request) => Promise<Response>) => Promise<Response>
87```
88
89### Transportation Layers
90
91See [Servie](https://github.com/serviejs/servie#implementers) for more information:
92
93```ts
94type Transport = (req: Request) => Promise<Response>
95```
96
97## TypeScript
98
99This project is written using [TypeScript](https://github.com/Microsoft/TypeScript) and publishes the types to NPM alongside the package.
100
101## Related Projects
102
103* [Superagent](https://github.com/visionmedia/superagent) - HTTP requests for node and browsers
104* [Fetch](https://github.com/github/fetch) - Browser polyfill for promise-based HTTP requests
105* [Axios](https://github.com/mzabriskie/axios) - HTTP request API based on Angular's `$http` service
106
107## License
108
109MIT