@studiohyperdrive/shortener NPM

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

CommonJS (Node 6+)

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

ESModule (ES2015+)

import Shortener from "@studiohyperdrive/shortener"

Configuration

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

const shortener = new Shortener(configuration)

The following parameters are accepted in the configuration:

Key	Description	Default
`target`required	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:

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

Presets

The alphabet parameter accepts multiple presets:

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

Example:

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

`.shorten(url)`

Shortens a given url.

Example:

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

result output:

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

`.getInfo()`

Gets information about the current configuration

Example:

const info = shortener.getInfo();

info output:

{
  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.

@everything-registry/sub-chunk-877

1.0.2

6 years ago

1.0.1

6 years ago

1.0.0

6 years ago