Repository files navigation

Sqids (pronounced "squids") is a small library that lets yougenerate unique IDs from numbers. It's good for link shortening, fast & URL-safe ID generation and decoding back into numbers for quicker database lookups.

Features:

• Encode multiple numbers - generate short IDs from one or several non-negative numbers
• Quick decoding - easily decode IDs back into numbers
• Unique IDs - generate unique IDs by shuffling the alphabet once
• ID padding - provide minimum length to make IDs more uniform
• URL safe - auto-generated IDs do not contain common profanity
• Randomized output - Sequential input provides nonconsecutive IDs
• Many implementations - Support for40+ programming languages

Good for:

• Generating IDs for public URLs (eg: link shortening)
• Generating IDs for internal systems (eg: event tracking)
• Decoding for quicker database lookups (eg: by primary keys)

Not good for:

• Sensitive data (this is not an encryption library)
• User IDs (can be decoded revealing user count)

yarn:

yarn add sqids

npm:

npm install sqids

cdnjs:

<scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/sqids/0.3.0/sqids.min.js"></script>

jsDelivr:

<scriptsrc="https://cdn.jsdelivr.net/npm/sqids/dist/sqids.min.js"></script>

Simple encode & decode:

importSqidsfrom'sqids'constsqids=newSqids()constid=sqids.encode([1,2,3])// "86Rf07"constnumbers=sqids.decode(id)// [1, 2, 3]

Note🚧 Because of the algorithm's design,multiple IDs can decode back into the same sequence of numbers. If it's important to your design that IDs are canonical, you have to manually re-encode decoded numbers and check that the generated ID matches.

Enforce aminimum length for IDs:

importSqidsfrom'sqids'constsqids=newSqids({minLength:10,})constid=sqids.encode([1,2,3])// "86Rf07xd4z"constnumbers=sqids.decode(id)// [1, 2, 3]

Randomize IDs by providing a custom alphabet:

importSqidsfrom'sqids'constsqids=newSqids({alphabet:'FxnXM1kBN6cuhsAvjW3Co7l2RePyY8DwaU04Tzt9fHQrqSVKdpimLGIJOgb5ZE',})constid=sqids.encode([1,2,3])// "B4aajs"constnumbers=sqids.decode(id)// [1, 2, 3]

Prevent specific words from appearing anywhere in the auto-generated IDs:

importSqidsfrom'sqids'constsqids=newSqids({blocklist:newSet(['86Rf07']),})constid=sqids.encode([1,2,3])// "se8ojk"constnumbers=sqids.decode(id)// [1, 2, 3]

MIT