Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/transitive-bullshit/check-links

Robustly checks an array of URLs for liveness. Extremely fast ⚡
https://github.com/transitive-bullshit/check-links

links urls validation

Last synced: 6 days ago
JSON representation

Robustly checks an array of URLs for liveness. Extremely fast ⚡

Awesome Lists containing this project

README 

        
# check-links



> Robustly checks an array of URLs for liveness.



[![NPM](https://img.shields.io/npm/v/check-links.svg)](https://www.npmjs.com/package/check-links) [![Build Status](https://github.com/transitive-bullshit/check-links/actions/workflows/test.yml/badge.svg)](https://github.com/transitive-bullshit/check-links/actions/workflows/test.yml) [![Prettier Code Formatting](https://img.shields.io/badge/code_style-prettier-brightgreen.svg)](https://prettier.io)



For each URL, it first attempts an HTTP HEAD request, and if that fails it will attempt

an HTTP GET request, retrying several times by default with exponential falloff.



This module handles concurrency and retry logic so you can check the status of thousands

of links quickly and robustly.



## Install



This module requires `node >= 18`.



```bash

npm install --save check-links

# or

yarn add check-links

# or

pnpm add check-links

```



Note: this package uses ESM and no longer provides a CommonJS export. See [here](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) for more info on how to use ESM modules.



## Usage



```js

import checkLinks from 'check-links'



const results = await checkLinks(['https://foo.com', 'https://404.com'])



results['https://foo.com'] // { status: 'alive', statusCode: 200 }

results['https://404.com'] // { status: 'dead', statusCode: 404 }



// example using a custom concurrency, timeout, and retry count

const results2 = await checkLinks(['https://foo.com', 'https://404.com'], {

  concurrency: 1,

  timeout: { request: 30000 },

  retry: { limit: 1 }

})

```



- Supports HTTP and HTTPS urls.

- Defaults to a 30 second timeout per HTTP request with 2 retries.

- Defaults to a Mac OS Chrome `user-agent`.

- Defaults to following redirects.

- All options use a [got options object](https://github.com/sindresorhus/got/blob/main/documentation/2-options.md).



## API



### [checkLinks](https://github.com/transitive-bullshit/check-links/blob/cf5fbcf0fc0bd150097034887b7c132384794549/index.js#L34-L51)



Robustly checks an array of URLs for liveness.



For each URL, it first attempts an HTTP HEAD request, and if that fails it will attempt

an HTTP GET request, retrying several times by default with exponential falloff.



Returns a `Map` that maps each input URL to an object

containing `status` and possibly `statusCode`.



`LivenessResult.status` will be one of the following:



- `alive` if the URL is reachable (2XX status code)

- `dead` if the URL is not reachable

- `invalid` if the URL was parsed as invalid or used an unsupported protocol



`LivenessResult.statusCode` will contain an integer HTTP status code if that URL resolved

properly.



Type: `function (urls, opts)`



- `urls` **[array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** Array of urls to test

- `opts` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional configuration options (any extra options are passed to [got](https://github.com/sindresorhus/got#options))

  - `opts.concurrency` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Maximum number of urls to resolve concurrently (optional, default `8`)



## Related



- [remark-lint-no-dead-urls](https://github.com/davidtheclark/remark-lint-no-dead-urls) - Remark lint plugin that inspired this module.



## License



MIT © [Travis Fischer](https://github.com/transitive-bullshit)



Support my OSS work by following me on twitter twitter