https://github.com/tcort/link-check
checks whether a hyperlink is alive (`200 OK`) or dead.
https://github.com/tcort/link-check
checker hyperlinks
Last synced: 5 months ago
JSON representation
checks whether a hyperlink is alive (`200 OK`) or dead.
- Host: GitHub
- URL: https://github.com/tcort/link-check
- Owner: tcort
- License: isc
- Created: 2016-01-12T03:29:03.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2025-01-27T23:19:47.000Z (8 months ago)
- Last Synced: 2025-05-12T02:09:48.127Z (5 months ago)
- Topics: checker, hyperlinks
- Language: JavaScript
- Size: 515 KB
- Stars: 43
- Watchers: 5
- Forks: 30
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# link-check
Checks whether a hyperlink is alive (`200 OK`) or dead.
## Installation
```console
npm install --save link-check
```
## Specification
A link is said to be 'alive' if an HTTP HEAD or HTTP GET for the given URL
eventually ends in a `200 OK` response. To minimize bandwidth, an HTTP HEAD
is performed. If that fails (e.g. with a `405 Method Not Allowed`), an HTTP
GET is performed. Redirects are followed.
In the case of `mailto:` links, this module validates the e-mail address using
[node-email-verifier](https://www.npmjs.com/package/node-email-verifier).
## API
### linkCheck(link, [opts,] callback)
Given a `link` and a `callback`, attempt an HTTP HEAD and possibly an HTTP GET.
Parameters:
* `url` string containing a URL.
* `opts` optional options object containing any of the following optional fields:
* `anchors` array of anchor strings (e.g. `[ "#foo", "#bar" ]`) for checking anchor links (e.g. `Foo`).
* `baseUrl` the base URL for relative links.
* `timeout` timeout in [zeit/ms](https://www.npmjs.com/package/ms) format. (e.g. `"2000ms"`, `20s`, `1m`). Default `10s`.
* `user_agent` the user-agent string. Default `${name}/${version}` (e.g. `link-check/4.5.5`)
* `aliveStatusCodes` an array of numeric HTTP Response codes which indicate that the link is alive. Entries in this array may also be regular expressions. Example: `[ 200, /^[45][0-9]{2}$/ ]`. Default `[ 200 ]`.
* `headers` a string based attribute value object to send custom HTTP headers. Example: `{ 'Authorization' : 'Basic Zm9vOmJhcg==' }`.
* `retryOn429` a boolean indicating whether to retry on a 429 (Too Many Requests) response. When true, if the response has a 429 HTTP code and includes an optional `retry-after` header, a retry will be attempted after the delay indicated in the `retry-after` header. If no `retry-after` header is present in the response or the `retry-after` header value is not valid according to [RFC7231](https://tools.ietf.org/html/rfc7231#section-7.1.3) (value must be in seconds), a default retry delay of 60 seconds will apply. This default can be overriden by the `fallbackRetryDelay` parameter.
* `retryCount` the number of retries to be made on a 429 response. Default `2`.
* `fallbackRetryDelay` the delay in [zeit/ms](https://www.npmjs.com/package/ms) format. (e.g. `"2000ms"`, `20s`, `1m`) for retries on a 429 response when no `retry-after` header is returned or when it has an invalid value. Default is `60s`.
* `callback` function which accepts `(err, result)`.
* `err` an Error object when the operation cannot be completed, otherwise `null`.
* `result` an object with the following properties:
* `link` the `link` provided as input
* `status` a string set to either `alive` or `dead`.
* `statusCode` the HTTP status code. Set to `0` if no HTTP status code was returned (e.g. when the server is down).
* `err` any connection error that occurred, otherwise `null`.
## Examples
```js
'use strict';
import linkCheck from 'link-check';
linkCheck('http://example.com', function (err, result) {
if (err) {
console.error(err);
return;
}
console.log(`${result.link} is ${result.status}`);
});
```
**With basic authentication:**
```js
'use strict';
import linkCheck from 'link-check';
linkCheck('http://example.com', { headers: { 'Authorization': 'Basic Zm9vOmJhcg==' } }, function (err, result) {
if (err) {
console.error(err);
return;
}
console.log(`${result.link} is ${result.status}`);
});
```
## Testing
```console
npm test
```
## License
See [LICENSE.md](https://github.com/tcort/link-check/blob/master/LICENSE.md)