sqids-clojure

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

sqids-clojure supports both Clojure and ClojureScript! In a Clojure environment, sqids-clojure wraps sqids-java. In a ClojureScript environment, sqids-clojure wraps sqids-javascript.

If you notice any issues with decoding or encoding, these are likely an issue in the upstream wrapped Sqids library.

Getting started

CLI/deps.edn dependency information:

;; maven
org.sqids/sqids-clojure {:mvn/version "1.0.15"}

Leiningen dependency information:

[org.sqids/sqids-clojure "1.0.15"]

After installation, require sqids-clojure:

(require '[org.sqids.clojure :as sqids])

Examples

Simple encode & decode:

(def sqids
  (sqids/sqids))

(def id
  (sqids/encode sqids [1 2 3])) ; "86Rf07"

(def numbers
  (sqids/decode sqids 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:

(def sqids
  (sqids/sqids {:min-length 10}))

(def id
  (sqids/encode sqids [1 2 3])) ; "86Rf07xd4z"

(def numbers
  (sqids/decode sqids id)) ; [1 2 3]

Randomize IDs by providing a custom alphabet:

(def sqids
  (sqids/sqids {:alphabet "FxnXM1kBN6cuhsAvjW3Co7l2RePyY8DwaU04Tzt9fHQrqSVKdpimLGIJOgb5ZE"}))

(def id
  (sqids/encode sqids [1 2 3])) ; "B4aajs"

(def numbers
  (sqids/decode sqids id)) ; [1 2 3]

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

(def sqids
  (sqids/sqids {:block-list #{"86Rf07"}}))

(def id
  (sqids/encode sqids [1 2 3])) ; "se8ojk"

(def numbers
  (sqids/decode sqids id)) ; [1 2 3]

License

MIT