`sqids`

This library implements the Sqids specification:

Specification: https://github.com/sqids/sqids-spec
Homepage: https://sqids.org
Default blocklist source: https://github.com/sqids/sqids-blocklist

It encodes a lists of non-negative integers into short, obfuscated (but not encrypted), URL-safe ids, and decodes them back. Typical uses are shortening database primary keys, or batches of keys, for public-facing URLs. Sqids is not suitable for security or privacy purposes: given the alphabet, ids are trivially reversible.

API documentation

Open the ../../apis/library_index.html#sqids link in a web browser.

Loading

To load all entities in this library, load the loader.lgt file:

| ?- logtalk_load(sqids(loader)).

Testing

To test this library predicates, load the tester.lgt file:

| ?- logtalk_load(sqids(tester)).

Usage

Encoding and decoding:

| ?- sqids::encode([1,2,3], Id).
Id = '86Rf07'.

| ?- sqids::decode('86Rf07', Numbers).
Numbers = [1, 2, 3].

Using encoding options:

| ?- sqids::encode([1,2,3], [min_length(10)], Id).
Id = '86Rf07xd4z'.

| ?- sqids::encode([1,2,3], [alphabet(abc)], Id).
Id = aacacbaa.

| ?- sqids::encode([1,2,3], [blocklist(['86Rf07'])], Id).
Id = se8ojk.

Options

The encode/3 and decode/3 predicates take an options list. The common option is:

alphabet(Atom) — an atom with at least three unique characters. The default value is the standard 62-character alphabet. In the case of the decode/3 predicate, it must be the same alphabet used to encode.

THere are also two encode/3 only options:

min_length(Integer) — an integer between 0 and 255 (default: 0).
blocklist(list(atom)) — words that must not occur in the generated identifier. When the canonical encoding contains a blocked word, an alternative encoding is tried. The default value is []. See the note below on the default blocklist.

Default profanity blocklist

This library does not bundle a default profanity blocklist (unlike some official Sqids implementations). The reference blocklist is maintained separately at:

https://github.com/sqids/sqids-blocklist

It can be supplied by the caller via the blocklist/1 option. This mirrors the reference TypeScript implementation itself, which imports its default blocklist from a separate JSON data file rather than embedding it in the core algorithm.

Arbitrary-precision integers

Most Sqids implementations impose an artificial maximum encodable value (typically Number.MAX_SAFE_INTEGER or a fixed-width integer type limit) because their host language lacks unbounded integers. Depending on the Prolog backend, integers are either bound or have arbitrary precision. Therefore, the encode/2-3 predicates only reject numbers that are not integers or that are negative with no explicit upper bound.

sqids