@studiohyperdrive/shortener

    1.0.2 • Public • Published

    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

    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
    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:

    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.

    Keywords

    none

    Install

    npm i @studiohyperdrive/shortener

    DownloadsWeekly Downloads

    32

    Version

    1.0.2

    License

    MIT

    Unpacked Size

    458 kB

    Total Files

    130

    Last publish

    Collaborators

    • bavo-vanderghote-shd
    • ian-emsens-shd
    • jeroenvalcke
    • tom-odb
    • brilniels
    • thomasbormans
    • sanderh
    • laurenspeeters
    • ex03495
    • rednas
    • denisvalcke
    • ibenvandeveire