Home

Awesome

url-unshort

CI NPM version

This library expands urls provided by url shortening services (see full list).

Why should I use it?

It has been argued that “shorteners are bad for the ecosystem as a whole”. In particular, if you're running a forum or a blog, such services might cause trouble for your users:

Also, short links are used to bypass the spam filters. So if you're implementing a domain black list for your blog comments, you might want to check where all those short links actually point to.

Installation

$ npm install url-unshort

Basic usage

const uu = require('url-unshort')()

try {
  const url = await uu.expand('http://goo.gl/HwUfwd')

  if (url) console.log('Original url is: ${url}')
  else console.log('This url can\'t be expanded')

} catch (err) {
  console.log(err);
}

Retrying errors

Temporary network errors are retried automatically once (options.request.retry=1 by default).

You may choose to retry some errors after an extended period of time using code like this:

const uu = require('url-unshort')()
const { isErrorFatal } = require('url-unshort')
let tries = 0

while (true) {
  try {
    tries++
    const url = await uu.expand('http://goo.gl/HwUfwd')

    // If url is expanded, it returns string (expanded url);
    // "undefined" is returned if service is unknown
    if (url) console.log(`Original url is: ${url}`)
    else console.log("This url can't be expanded")
    break

  } catch (err) {
    // use isErrorFatal function to check if url can be retried or not
    if (isErrorFatal(err)) {
      // this url can't be expanded (e.g. 404 error)
      console.log(`Unshort error (fatal): ${err}`)
      break
    }

    // Temporary error, trying again in 10 minutes
    // (5xx errors, ECONNRESET, etc.)
    console.log(`Unshort error (retrying): ${err}`)
    if (tries >= 3) {
      console.log(`Too many errors, aborting`)
      break
    }
    await new Promise(resolve => setTimeout(resolve, 10 * 60 * 1000))
  }
}

API

Creating an instance

When you create an instance, you can pass an options object to fine-tune unshortener behavior.

const uu = require('url-unshort')({
  nesting: 3,
  cache: {
    get: async key => {},
    set: async (key, value) => {}
  }
});

Available options are:

uu.expand(url) -> Promise

Expand an URL supplied. If we don't know how to expand it, returns null.

const uu = require('url-unshort')();

try {
  const url = await uu.expand('http://goo.gl/HwUfwd')

  if (url) console.log('Original url is: ${url}')
  // no shortening service or an unknown one is used
  else console.log('This url can\'t be expanded')

} catch (err) {
  console.log(err)
}

uu.add(domain [, options])

Add a new url shortening service (domain name or an array of them) to the white list of domains we know how to expand.

uu.add([ 'tinyurl.com', 'bit.ly' ])

The default behavior will be to follow the URL with a HEAD request and check the status code. If it's 3xx, return the Location header. You can override this behavior by supplying your own function in options.

Options:

Example:

const uu = require('url-unshort')()

uu.add('notlong.com', {
  match: '^(https?:)//[a-zA-Z0-9_-]+[.]notlong[.]com/'
})

uu.add('tw.gs', {
  link_selector: '#lurllink > a'
})

uu.remove(domain)

(String|Array|Undefined). Opposite to .add(). Remove selected domains from instance config. If no params passed - remove everything.

Security considerations

Only http and https protocols are allowed in the output. Browsers technically support redirects to other protocols (like ftp or magnet), but most url shortening services limit redirects to http and https anyway. In case service redirects to an unknown protocol, expand() will return an error.

expand() function returns url from the url shortening as is without any escaping or even ensuring that the url is valid. If you want to guarantee a valid url as an output, you're encouraged to re-encode it like this:

var URL = require('url');

url = await uu.expand('http://goo.gl/HwUfwd')

if (url) url = URL.format(URL.parse(url, null, true))

console.log(url));

License

MIT