{"id":13454643,"url":"https://github.com/nodeca/url-unshort","last_synced_at":"2025-04-07T08:27:20.768Z","repository":{"id":36022142,"uuid":"40317558","full_name":"nodeca/url-unshort","owner":"nodeca","description":"Short links expander for node.js","archived":false,"fork":false,"pushed_at":"2023-06-19T01:54:11.000Z","size":97,"stargazers_count":112,"open_issues_count":0,"forks_count":13,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-04-14T04:22:27.137Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nodeca.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null},"funding":{"open_collective":"puzrin","patreon":"puzrin"}},"created_at":"2015-08-06T17:17:58.000Z","updated_at":"2024-02-23T19:05:56.000Z","dependencies_parsed_at":"2022-08-17T22:55:56.364Z","dependency_job_id":null,"html_url":"https://github.com/nodeca/url-unshort","commit_stats":{"total_commits":95,"total_committers":5,"mean_commits":19.0,"dds":0.2421052631578947,"last_synced_commit":"b6c77826bb3f750cafdcd3ef55dfe065133109b8"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeca%2Furl-unshort","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeca%2Furl-unshort/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeca%2Furl-unshort/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeca%2Furl-unshort/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nodeca","download_url":"https://codeload.github.com/nodeca/url-unshort/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246429468,"owners_count":20775806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T08:00:56.286Z","updated_at":"2025-04-07T08:27:20.751Z","avatar_url":"https://github.com/nodeca.png","language":"JavaScript","funding_links":["https://opencollective.com/puzrin","https://patreon.com/puzrin"],"categories":["Packages","包","目录","URL","Number"],"sub_categories":["URL"],"readme":"# url-unshort\n\n[![CI](https://github.com/nodeca/url-unshort/actions/workflows/ci.yml/badge.svg)](https://github.com/nodeca/url-unshort/actions/workflows/ci.yml)\n[![NPM version](https://img.shields.io/npm/v/url-unshort.svg?style=flat)](https://www.npmjs.org/package/url-unshort)\n\n\u003e This library expands urls provided by url shortening services (see [full list](https://github.com/nodeca/url-unshort/blob/master/domains.yml)).\n\n\n## Why should I use it?\n\nIt has been [argued](http://joshua.schachter.org/2009/04/on-url-shorteners) that\n“shorteners are bad for the ecosystem as a whole”. In particular, if you're\nrunning a forum or a blog, such services might cause trouble for your users:\n\n - such links load slower than usual (shortening services require an extra DNS\n   and HTTP request)\n - it adds another point of failure (should this service go down, the links will\n   die; [301works](https://archive.org/details/301works) tries to solve this,\n   but it's better to avoid the issue in the first place)\n - users don't see where the link points to (tinyurl previews don't *really*\n   solve this)\n - it can be used for user activity tracking\n - certain shortening services are displaying ads before redirect\n - shortening services can be malicious or be hacked so they could redirect to\n   a completely different place next month\n\nAlso, short links are used to bypass the spam filters. So if you're implementing\na domain black list for your blog comments, you might want to check where all\nthose short links *actually* point to.\n\n\n## Installation\n\n```js\n$ npm install url-unshort\n```\n\n## Basic usage\n\n```js\nconst uu = require('url-unshort')()\n\ntry {\n  const url = await uu.expand('http://goo.gl/HwUfwd')\n\n  if (url) console.log('Original url is: ${url}')\n  else console.log('This url can\\'t be expanded')\n\n} catch (err) {\n  console.log(err);\n}\n```\n\n## Retrying errors\n\nTemporary network errors are retried automatically once (`options.request.retry=1` by default).\n\nYou may choose to retry some errors after an extended period of time using code like this:\n\n```js\nconst uu = require('url-unshort')()\nconst { isErrorFatal } = require('url-unshort')\nlet tries = 0\n\nwhile (true) {\n  try {\n    tries++\n    const url = await uu.expand('http://goo.gl/HwUfwd')\n\n    // If url is expanded, it returns string (expanded url);\n    // \"undefined\" is returned if service is unknown\n    if (url) console.log(`Original url is: ${url}`)\n    else console.log(\"This url can't be expanded\")\n    break\n\n  } catch (err) {\n    // use isErrorFatal function to check if url can be retried or not\n    if (isErrorFatal(err)) {\n      // this url can't be expanded (e.g. 404 error)\n      console.log(`Unshort error (fatal): ${err}`)\n      break\n    }\n\n    // Temporary error, trying again in 10 minutes\n    // (5xx errors, ECONNRESET, etc.)\n    console.log(`Unshort error (retrying): ${err}`)\n    if (tries \u003e= 3) {\n      console.log(`Too many errors, aborting`)\n      break\n    }\n    await new Promise(resolve =\u003e setTimeout(resolve, 10 * 60 * 1000))\n  }\n}\n```\n\n\n## API\n\n### Creating an instance\n\nWhen you create an instance, you can pass an options object to fine-tune unshortener behavior.\n\n```js\nconst uu = require('url-unshort')({\n  nesting: 3,\n  cache: {\n    get: async key =\u003e {},\n    set: async (key, value) =\u003e {}\n  }\n});\n```\n\nAvailable options are:\n\n- **nesting** (Number, default: `3`) - stop resolving urls\n  when `nesting` amount of redirects is reached.\n\n  It happens if one shortening service refers to a link belonging to\n  another shortening service which in turn points to yet another one\n  and so on.\n\n  If this limit is reached, `expand()` will return an error.\n\n- **cache** (Object) - set a custom cache implementation (e.g. if you wish\n  to store urls in Redis).\n\n  You need to specify 2 promise-based functions, `set(key, value)` \u0026 `get(key)`.\n\n- **request** (Object) - default options for\n  [got](https://github.com/sindresorhus/got) in `.request()` method. Can be\n  used to set custom `User-Agent` and other headers.\n\n\n### uu.expand(url) -\u003e Promise\n\nExpand an URL supplied. If we don't know how to expand it, returns `null`.\n\n```js\nconst uu = require('url-unshort')();\n\ntry {\n  const url = await uu.expand('http://goo.gl/HwUfwd')\n\n  if (url) console.log('Original url is: ${url}')\n  // no shortening service or an unknown one is used\n  else console.log('This url can\\'t be expanded')\n\n} catch (err) {\n  console.log(err)\n}\n```\n\n### uu.add(domain [, options])\n\nAdd a new url shortening service (domain name or an array of them) to the white\nlist of domains we know how to expand.\n\n```js\nuu.add([ 'tinyurl.com', 'bit.ly' ])\n```\n\nThe default behavior will be to follow the URL with a HEAD request and check\nthe status code. If it's `3xx`, return the `Location` header. You can override\nthis behavior by supplying your own function in options.\n\nOptions:\n\n- **aliases** (Array) - Optional. List of alternate domaine names, if exist.\n- **match** (String|RegExp) - Optional. Custom regexp to use for URL match.\n  For example, if you need to match wildcard prefixes or country-specific\n  suffixes. If used with `validate`, then regexp may be not precise, only to\n  filter out noise. If `match` not passed, then exact value auto-generated from\n  `domain` \u0026 `aliases`.\n- **validate** (Function) - Optional. Does exact URL check, when complex logic\n  required and regexp is not enouth (when `match` is only preliminary). See\n  `./lib/providers/*` for example.\n- **fetch**  (Function) - Optional. Specifies custom function to retrieve expanded\n  url, see `./lib/providers/*` for examples. If not set - default method used\n  (it checks 30X redirect codes \u0026 `\u003cmeta http-equiv=\"refresh\" content='...'\u003e`\n  in HTML).\n- **link_selector** (String) - Optional. Some sites may return HTML pages instead\n  of 302 redirects. This option allows use jquery-like selector to extract\n  `\u003ca href=\"...\"\u003e` value.\n\nExample:\n\n```js\nconst uu = require('url-unshort')()\n\nuu.add('notlong.com', {\n  match: '^(https?:)//[a-zA-Z0-9_-]+[.]notlong[.]com/'\n})\n\nuu.add('tw.gs', {\n  link_selector: '#lurllink \u003e a'\n})\n```\n\n### uu.remove(domain)\n\n(String|Array|Undefined). Opposite to `.add()`. Remove selected domains from\ninstance config. If no params passed - remove everything.\n\n\n## Security considerations\n\nOnly `http` and `https` protocols are allowed in the output. Browsers technically\nsupport redirects to other protocols (like `ftp` or `magnet`), but most url\nshortening services limit redirects to `http` and `https` anyway. In case\nservice redirects to an unknown protocol, `expand()` will return an error.\n\n`expand()` function returns url from the url shortening **as is** without any\nescaping or even ensuring that the url is valid. If you want to guarantee a\nvalid url as an output, you're encouraged to re-encode it like this:\n\n```js\nvar URL = require('url');\n\nurl = await uu.expand('http://goo.gl/HwUfwd')\n\nif (url) url = URL.format(URL.parse(url, null, true))\n\nconsole.log(url));\n```\n\n## License\n\n[MIT](https://raw.github.com/nodeca/url-unshort/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodeca%2Furl-unshort","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnodeca%2Furl-unshort","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodeca%2Furl-unshort/lists"}