diff --git a/documentation/quickstart.md b/documentation/quickstart.md
index dde0930c6..3d23ea122 100644
--- a/documentation/quickstart.md
+++ b/documentation/quickstart.md
@@ -1,4 +1,4 @@
-# Quick start guide
+# Quick Start Guide
## Getting and posting data with promises
@@ -11,19 +11,24 @@ const url = 'https://httpbin.org/anything';
const response = await got(url);
```
-The call returns a Promise<[Response](3-streams.md#response-1)>
. If the body contains json, it can be retreived directly:
+The call returns a Promise<[Response](3-streams.md#response-1)>
. If the body contains JSON, it can be retrieved directly:
```js
+import got from 'got';
+
const url = 'https://httpbin.org/anything';
const data = await got(url).json();
```
The similar [got.text](1-promise.md#promisetext)
method returns plain text.
-All `got` methods accepts an options object for passing extra informations, such as headers:
+All `got` methods accept an options object for passing extra configuration, such as headers:
```js
+import got from 'got';
+
const url = 'https://httpbin.org/anything';
+
const options = {
headers: {
'Custom-Header': 'Quick start',
@@ -39,15 +44,20 @@ const data = await got(url, options).json();
A `POST` request is very similar:
```js
+import got from 'got';
+
const url = 'https://httpbin.org/anything';
+
const options = {
- json: { documentName: 'Quick Start' },
+ json: {
+ documentName: 'Quick Start',
+ },
};
const data = await got.post(url, options);
```
-The request body is passed in the options object, `json` property will automatically set headers accordingly. Custom headers can be added exactly as above.
+The request body is passed in the options object. The `json` property will automatically set headers accordingly. Custom headers can be added exactly as above.
## Using streams
@@ -55,24 +65,29 @@ The [Stream API](3-streams.md) allows to leverage [Node.js Streams](https://node
```js
import got from 'got';
-import fs from 'fs';
-import { pipeline } from 'stream';
+import fs from 'node:fs';
+import {pipeline} from 'node:stream';
const url = 'https://httpbin.org/anything';
+
const options = {
- json: { documentName: 'Quick Start' },
+ json: {
+ documentName: 'Quick Start',
+ },
};
const gotStream = got.stream.post(url, options);
+
const outStream = fs.createWriteStream('anything.json');
+
pipeline(gotStream, outStream, error => {
- if (error) console.error(error.message);
+ if (error) console.error(error.message);
});
```
## Options
-Options can be set at client level and reused in subsequent queries:
+Options can be set at the client level and reused in subsequent queries:
```js
import got from 'got';
@@ -89,27 +104,27 @@ const client = got.extend(options);
export default client;
```
-Some noticable common options are (opinionated :blush:):
- - [searchParams](./2-options.md#searchparams): a query string object.
- - [prefixUrl](./2-options.md#prefixurl): prepended to query pathes. Pathes must be relative to prefix, i.e. not begin with a `/`.
- - [method](./2-options.md#method): the HTTP method name.
- - [headers](./2-options.md#headers): query headers.
- - [json](./2-options.md#json): JSON body.
- - [form](./2-options.md#form): a form query string object.
-
-See documentation for other [options](./2-options.md#options).
+Some noticable common options are:
+- [`searchParams`](2-options.md#searchparams): A query string object.
+- [`prefixUrl`](2-options.md#prefixurl): Prepended to query pathes. Pathes must be relative to prefix, i.e. not begin with a `/`.
+- [`method`](2-options.md#method): The HTTP method name.
+- [`headers`](2-options.md#headers): Query headers.
+- [`json`](2-options.md#json): JSON body.
+- [`form`](2-options.md#form): A form query string object.
+
+See documentation for other [options](2-options.md#options).
## Errors
-Both Promise and Stream APIs throws error with metadata. They are handled according to the API used.
+Both Promise and Stream APIs throw errors with metadata.
```js
import got from 'got';
try {
- const data = await got.get('https://httpbin.org/status/404');
+ const data = await got.get('https://httpbin.org/status/404');
} catch (error) {
- console.error(error.message);
+ console.error(error.message);
}
```
@@ -123,22 +138,28 @@ const stream = got.stream
});
```
-## Miscalleneous
+## Miscellaneous
The HTTP method name can also be given as an option, this may be convenient when it is known only at runtime:
```js
+import got from 'got';
+
const url = 'https://httpbin.org/anything';
+
const method = 'POST';
+
const options = {
- json: { documentName: 'Quick Start' },
method,
+ json: {
+ documentName: 'Quick Start',
+ },
};
const data = await got(url, options);
```
-For most applications, http client just do `GET` and `POST` queries (`PUT`, `PATCH` or `DELETE` methods work similarly).
+For most apps, HTTP clients just do `GET` and `POST` queries (`PUT`, `PATCH` or `DELETE` methods work similarly).
The following sections will give some pointers to more advanced usage.
### Timeouts
@@ -159,22 +180,26 @@ const client = got.extend(options);
export default client;
```
-The above set a global timeout of 10000 ms for all requests issued by the exported `client`. Like all options, timeouts can also be set at request level. See [timeout options](./6-timeout.md#timeout-options).
+The above sets a global timeout of 10000 milliseconds for all requests issued by the exported `client`. Like all options, timeouts can also be set at the request level. See the [`timeout` option](6-timeout.md#timeout-options).
### Retries
-A failed request is retried twice, retry policy may be tuned with a [`retry`](./7-retry.md#retry) option object.
+A failed request is retried twice, retry policy may be tuned with a [`retry`](7-retry.md#retry) options object.
```js
+import got from 'got';
+
const options = {
retry: {
limit: 5,
- errorCodes: ['ETIMEDOUT'],
+ errorCodes: [
+ 'ETIMEDOUT'
+ ],
},
};
```
-Retries with stream are a little trickier, see [`stream.on('retry', ...)`](./3-streams.md#streamonretry-).
+Retries with stream are a little trickier, see [`stream.on('retry', …)`](3-streams.md#streamonretry-).
### Hooks
@@ -184,12 +209,14 @@ Hooks are custom functions called on some request events:
import got from 'got';
const logRetry = (error, retryCount) => {
- console.error(`Retrying after error ${error.code}, retry #: ${retryCount}`);
+ console.error(`Retrying after error ${error.code}, retry #: ${retryCount}`);
};
const options = {
hooks: {
- beforeRetry: [logRetry]
+ beforeRetry: [
+ logRetry,
+ ],
},
};
@@ -198,9 +225,9 @@ const client = got.extend(options);
export default client;
```
-*Note that handlers are given as arrays*, thus multiple handlers can be given. See documentation for other possible [hooks](./9-hooks.md#hooks-api).
+*Note that handlers are given as arrays*, thus multiple handlers can be given. See documentation for other possible [hooks](9-hooks.md#hooks-api).
### Going further
-There's a lot more to discover in the [documentation](../readme.md#documentation) and [tips](./tips.md#tips).
-Among others, `Got` can handle [cookies](./tips.md#cookies), [pagination](./4-pagination.md#pagination-api), [cache](./cache.md#cache). Read the doc before implementing something that is already done by `Got` :innocent:.
\ No newline at end of file
+There is a lot more to discover in the [documentation](../readme.md#documentation) and [tips](tips.md#tips).
+Among others, `Got` can handle [cookies](tips.md#cookies), [pagination](4-pagination.md#pagination-api), [cache](cache.md#cache). Read the documentation before implementing something that is already done by `Got` :innocent:.