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 | ```
|
14 | npm install popsicle --save
|
15 | ```
|
16 |
|
17 | ## Usage
|
18 |
|
19 | ```js
|
20 | import { transport, request } from 'popsicle'
|
21 |
|
22 | const req = request('http://example.com') // Creates a `Request` instance.
|
23 | const res = await transport()(req) // Transports `Request` and returns `Response` instance.
|
24 | ```
|
25 |
|
26 | Thin 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 |
|
32 | Normalizes 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 |
|
62 | Transports 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 |
|
83 | See [Throwback](https://github.com/serviejs/throwback#usage) for more information:
|
84 |
|
85 | ```ts
|
86 | type Plugin = (req: Request, next: (req?: Request) => Promise<Response>) => Promise<Response>
|
87 | ```
|
88 |
|
89 | ### Transportation Layers
|
90 |
|
91 | See [Servie](https://github.com/serviejs/servie#implementers) for more information:
|
92 |
|
93 | ```ts
|
94 | type Transport = (req: Request) => Promise<Response>
|
95 | ```
|
96 |
|
97 | ## TypeScript
|
98 |
|
99 | This 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 |
|
109 | MIT
|