JavaScripting

The definitive source of the best
JavaScript libraries, frameworks, and plugins.


  • ×

    Hashids.js

    A small JavaScript class to generate YouTube-like hashids from one or many numbers. This is a client-side version of Node.js version.
    Filed under 

    • 🔾58%Overall
    • 2,568
    • 11.2 days
    • 🕩148
    • 👥11

    hashids

    Build Status Coveralls Status NPM downloads NPM version Greenkeeper badge License Chat

    Hashids is small JavaScript library to generate YouTube-like ids from numbers. Use it when you don't want to expose your database ids to the user: http://hashids.org/javascript

    Getting started

    Install Hashids via:

    • node.js: yarn add hashids
    • bower: bower install hashids
    • jam: jam install hashids

    (or just use the code at dist/hashids.js)

    Use in ESM-compatible environments (webpack, modern browsers):

    import Hashids from 'hashids'
    const hashids = new Hashids()
    
    console.log(hashids.encode(1))
    

    Use in Node.js:

    const Hashids = require('hashids/cjs')
    const hashids = new Hashids()
    
    console.log(hashids.encode(1))
    

    Use in the browser without ESM (wherever ES5 is supported; 5KB):

    <script type="text/javascript" src="hashids.min.js"></script>
    <script type="text/javascript">
    
        var hashids = new Hashids();
        console.log(hashids.encode(1));
    
    </script>
    

    Use in TypeScript:

    import Hashids from 'hashids';
    
    const hashids = new Hashids();
    console.log(hashids.encode(1));
    

    If you get errors stating: Cannot find name 'BigInt', add "esnext.bigint" or "esnext" to your tsconfig.json file, under "lib":

    {
      "compilerOptions": {
        ...
        "lib": [
          "esnext.bigint",
          ...
        ]
      }
    }
    

    Quick example

    const hashids = new Hashids()
    
    const id = hashids.encode(1, 2, 3) // o2fXhV
    const numbers = hashids.decode(id) // [1, 2, 3]
    

    More options

    A few more ways to pass to encode():

    const hashids = new Hashids()
    
    console.log(hashids.encode(1, 2, 3)) // o2fXhV
    console.log(hashids.encode([1, 2, 3])) // o2fXhV
    // strings containing integers are coerced to numbers:
    console.log(hashids.encode('1', '2', '3')) // o2fXhV
    console.log(hashids.encode(['1', '2', '3'])) // o2fXhV
    // BigInt support:
    console.log(hashids.encode([1n, 2n, 3n])) // o2fXhV
    // Hex notation BigInt:
    console.log(hashids.encode([0x1n, 0x2n, 0x3n])) // o2fXhV
    

    Make your ids unique:

    Pass a "salt" to make your ids unique (e.g. a project name):

    var hashids = new Hashids('My Project')
    console.log(hashids.encode(1, 2, 3)) // Z4UrtW
    
    var hashids = new Hashids('My Other Project')
    console.log(hashids.encode(1, 2, 3)) // gPUasb
    

    Use padding to make your ids longer:

    Note that ids are only padded to fit at least a certain length. It doesn't mean that your ids will be exactly that length.

    const hashids = new Hashids() // no padding
    console.log(hashids.encode(1)) // jR
    
    const hashids = new Hashids('', 10) // pad to length 10
    console.log(hashids.encode(1)) // VolejRejNm
    

    Pass a custom alphabet:

    const hashids = new Hashids('', 0, 'abcdefghijklmnopqrstuvwxyz') // all lowercase
    console.log(hashids.encode(1, 2, 3)) // mdfphx
    

    Default alphabet is abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890.

    Since v2.0 you can even use emojis as the alphabet.

    Encode hex instead of numbers:

    Useful if you want to encode numbers like Mongo's ObjectIds.

    Note that there is no limit on how large of a hex number you can pass.

    var hashids = new Hashids()
    
    var id = hashids.encodeHex('507f1f77bcf86cd799439011') // y42LW46J9luq3Xq9XMly
    var hex = hashids.decodeHex(id) // 507f1f77bcf86cd799439011
    

    Please note that this is not the equivalent of:

    const hashids = new Hashids()
    
    const id = Hashids.encode(BigInt('0x507f1f77bcf86cd799439011')) // y8qpJL3ZgzJ8lWk4GEV
    const hex = Hashids.decode(id)[0].toString(16) // 507f1f77bcf86cd799439011
    

    The difference between the two is that the built-in encodeHex will always result in the same length, even if it contained leading zeros.

    For example hashids.encodeHex('00000000') would encode to qExOgK7 and decode back to '00000000' (length information is preserved).

    Pitfalls

    1. When decoding, output is always an array of numbers (even if you encode only one number):

      const hashids = new Hashids()
      
      const id = hashids.encode(1)
      console.log(hashids.decode(id)) // [1]
      
    2. Encoding negative numbers is not supported.

    3. If you pass bogus input to encode(), an empty string will be returned:

      const hashids = new Hashids()
      
      const id = hashids.encode('123a')
      console.log(id === '') // true
      
    4. Do not use this library as a security tool and do not encode sensitive data. This is not an encryption library.

    Randomness

    The primary purpose of Hashids is to obfuscate ids. It's not meant or tested to be used as a security or compression tool. Having said that, this algorithm does try to make these ids random and unpredictable:

    No repeating patterns showing there are 3 identical numbers in the id:

    const hashids = new Hashids()
    console.log(hashids.encode(5, 5, 5)) // A6t1tQ
    

    Same with incremented numbers:

    const hashids = new Hashids()
    
    console.log(hashids.encode(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)) // wpfLh9iwsqt0uyCEFjHM
    
    console.log(hashids.encode(1)) // jR
    console.log(hashids.encode(2)) // k5
    console.log(hashids.encode(3)) // l5
    console.log(hashids.encode(4)) // mO
    console.log(hashids.encode(5)) // nR
    

    Curses! #\$%@

    This code was written with the intent of placing created ids in visible places, like the URL. Therefore, by default the algorithm tries to avoid generating most common English curse words by generating ids that never have the following letters next to each other:

    c, f, h, i, s, t, u
    

    You may customize the chars that shouldn't be placed next to each other by providing a 4th argument to the Hashids constructor:

    // first 4 arguments will fallback to defaults (empty salt, no minimum length, default alphabet)
    const hashids = new Hashids(undefined, undefined, undefined, 'zyxZYX')
    

    BigInt

    If your environment supports BigInt, you can use the standard API to encode and decode them the same way as ordinary numbers.

    Trying to decode a BigInt-encoded hashid on an unsupported environment will throw an error.

    License

    MIT License. See the LICENSE file. You can use Hashids in open source projects and commercial products. Don't break the Internet. Kthxbye.

    Show All