Shortener

Light-weight JavaScript utility to create an url shortener with


_{Only ~3.5kb, no external dependencies, supports NodeJS 6+ and ES2015+}

- Lightweight: ~3.5kb in size, vanilla JavaScript and no external dependencies 🐜
- Fast: generates 100 shortened urls in less than 5ms 🚤
- Configurable: lends ultimate control over the output format of the shortened urls 🛠️
- Tested: 100% code coverage 🎉
- MIT Licensed: free for personal and commercial use ❤️

*

How to install

Install with:
- NPM: npm install @studiohyperdrive/shortener
- Yarn: yarn add @studiohyperdrive/shortener

How to use

$3

``javascript
const Shortener = require("@studiohyperdrive/shortener")
`

$3

`javascript
import Shortener from "@studiohyperdrive/shortener"
`

$3

An instance of the shortener can be created by calling the constructor with a configuration.

`javascript
const shortener = new Shortener(configuration)
`

The following parameters are accepted in the configuration:

| Key | Description | Default |
|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
| targetrequired | A valid url to append the shortened id to, by default the id is added at the end of the url.

Optionally, you can pass a placeholder {id} to reposition the id anywhere in the url.
Example: https://short.er?id={0} → https://shorter?id=SP4C3 | none |
| length | Length of the shortened id. | 5 |
| alphabet | Alphabet with allowed characters for generating the shortened id,
you can also choose one the included presets. | base58 |

Example:

`javascript
const shortener = new Shortener({
target: "https://short.er"
length: 6,
alphabet: "0123456789abcdefABCDEF"
})
`

$3

The alphabet parameter accepts multiple presets:

| Name | Value |
| -------------- | ---------------------------------------------------------------- |
| alphanumeric | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 |
| alphabetic | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ |
| numeric | 0123456789 |
| base58 | abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ123456789 |
| base56 | abcdefghijkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789 |
| base32 | ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 |
| base16 | ABCDEF0123456789 |

Example:

`javascript
const shortener = new Shortener({
target: "https://short.er"
alphabet: "alphanumeric"
})
`

$3

Shortens a given url.

Example:

`javascript
const result = shortener.shorten("https://www.google.com");
`

result output:

`javascript
{
id: "6VYN9",
original: "https://www.google.com",
target: "https://short.er/6VYN9"
}
`

$3

Gets information about the current configuration

Example:

`javascript
const info = shortener.getInfo();
`

info output:

`javascript
{
config: {
target: 'https://short.er',
length: 5,
alphabet: 'abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ123456789'
},
collisionInfo: {
// The amount of unique shortened id's that can be generated
// with the current configuration of length & alphabet
possibilities: 656356768,

//The probability of generating a non-unique shortened id
probability: 1.5235616493254474e-9
}
}
``

Examples

A minimal usage example for Express + Mongoose can be found here

Contributing

Feel free to provide feedback, open issues or create pull-requests to this repository.

License

Shortener is MIT licensed by Studio Hyperdrive.