Home

Awesome

Sqids Ruby

Gem Version Github Actions Downloads

Sqids (pronounced "squids") is a small library that lets you generate 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:

šŸ§° Use-cases

Good for:

Not good for:

šŸš€ Getting started

Add this line to your application's Gemfile:

gem 'sqids'

And then execute:

bundle

Or install it via:

gem install sqids

šŸ‘©ā€šŸ’» Examples

Simple encode & decode:

sqids = Sqids.new
id = sqids.encode([1, 2, 3]) # '86Rf07'
numbers = 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 a minimum length for IDs:

sqids = Sqids.new(min_length: 10)
id = sqids.encode([1, 2, 3]) # '86Rf07xd4z'
numbers = sqids.decode(id) # [1, 2, 3]

Randomize IDs by providing a custom alphabet:

sqids = Sqids.new(alphabet: 'FxnXM1kBN6cuhsAvjW3Co7l2RePyY8DwaU04Tzt9fHQrqSVKdpimLGIJOgb5ZE')
id = sqids.encode([1, 2, 3]) # 'B4aajs'
numbers = sqids.decode(id) # [1, 2, 3]

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

sqids = Sqids.new(blocklist: Set.new(%w[86Rf07]))
id = sqids.encode([1, 2, 3]) # 'se8ojk'
numbers = sqids.decode(id) # [1, 2, 3]

[!WARNING]
If you provide a large custom blocklist and/or custom alphabet, calls to Sqid.new can take ~1ms. You should create a singleton instance of Sqid at service start and reusing that rather than repeatedly calling Squid.new

šŸ“ License

MIT