Class: MySqids

Inherits:
Object
  • Object
show all
Defined in:
lib/encoded_id/encoders/my_sqids.rb

Overview

Sqids (pronounced “squids”) is a library that generates short, unique, non-sequential IDs from numbers. It’s useful for obfuscating database IDs, creating URL-friendly identifiers, and generating human-readable codes.

Key features:

  • Reversible: encoded IDs can be decoded back to the original numbers

  • Customizable: supports custom alphabets, minimum lengths, and blocklists

  • Collision-free: same input always produces the same output

  • Blocklist filtering: automatically regenerates IDs that contain blocked words

The algorithm uses a shuffling mechanism based on the input numbers to select characters from a customized alphabet, ensuring that sequential numbers produce non-sequential IDs.

Direct Known Subclasses

SqidsWithBlocklistMode

Constant Summary collapse

DEFAULT_ALPHABET = 
"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
DEFAULT_MIN_LENGTH =

Default minimum length of 0 means no padding is applied to generated IDs

0
DEFAULT_BLOCKLIST =

rubocop:disable Metrics/CollectionLiteralLength, Layout/LineLength Default blocklist containing words that should not appear in generated IDs The blocklist prevents offensive or inappropriate words from appearing in IDs by regenerating IDs that contain these patterns.

%w[0rgasm 1d10t 1d1ot 1di0t 1diot 1eccacu10 1eccacu1o 1eccacul0
1eccaculo 1mbec11e 1mbec1le 1mbeci1e 1mbecile a11upat0 a11upato a1lupat0 a1lupato aand ah01e ah0le aho1e ahole al1upat0 al1upato allupat0 allupato ana1 ana1e anal anale anus arrapat0 arrapato arsch arse ass b00b b00be b01ata b0ceta b0iata b0ob b0obe b0sta b1tch b1te b1tte ba1atkar balatkar bastard0 bastardo batt0na battona bitch bite bitte bo0b bo0be bo1ata boceta boiata boob boobe bosta bran1age bran1er bran1ette bran1eur bran1euse branlage branler branlette branleur branleuse c0ck c0g110ne c0g11one c0g1i0ne c0g1ione c0gl10ne c0gl1one c0gli0ne c0glione c0na c0nnard c0nnasse c0nne c0u111es c0u11les c0u1l1es c0u1lles c0ui11es c0ui1les c0uil1es c0uilles c11t c11t0 c11to c1it c1it0 c1ito cabr0n cabra0 cabrao cabron caca cacca cacete cagante cagar cagare cagna cara1h0 cara1ho caracu10 caracu1o caracul0 caraculo caralh0 caralho cazz0 cazz1mma cazzata cazzimma cazzo ch00t1a ch00t1ya ch00tia ch00tiya ch0d ch0ot1a ch0ot1ya ch0otia ch0otiya ch1asse ch1avata ch1er ch1ng0 ch1ngadaz0s ch1ngadazos ch1ngader1ta ch1ngaderita ch1ngar ch1ngo ch1ngues ch1nk chatte chiasse chiavata chier ching0 chingadaz0s chingadazos chingader1ta chingaderita chingar chingo chingues chink cho0t1a cho0t1ya cho0tia cho0tiya chod choot1a choot1ya chootia chootiya cl1t cl1t0 cl1to clit clit0 clito cock cog110ne cog11one cog1i0ne cog1ione cogl10ne cogl1one cogli0ne coglione cona connard connasse conne cou111es cou11les cou1l1es cou1lles coui11es coui1les couil1es couilles cracker crap cu10 cu1att0ne cu1attone cu1er0 cu1ero cu1o cul0 culatt0ne culattone culer0 culero culo cum cunt d11d0 d11do d1ck d1ld0 d1ldo damn de1ch deich depp di1d0 di1do dick dild0 dildo dyke encu1e encule enema enf01re enf0ire enfo1re enfoire estup1d0 estup1do estupid0 estupido etr0n etron f0da f0der f0ttere f0tters1 f0ttersi f0tze f0utre f1ca f1cker f1ga fag fica ficker figa foda foder fottere fotters1 fottersi fotze foutre fr0c10 fr0c1o fr0ci0 fr0cio fr0sc10 fr0sc1o fr0sci0 fr0scio froc10 froc1o froci0 frocio frosc10 frosc1o frosci0 froscio fuck g00 g0o g0u1ne g0uine gandu go0 goo gou1ne gouine gr0gnasse grognasse haram1 harami haramzade hund1n hundin id10t id1ot idi0t idiot imbec11e imbec1le imbeci1e imbecile j1zz jerk jizz k1ke kam1ne kamine kike leccacu10 leccacu1o leccacul0 leccaculo m1erda m1gn0tta m1gnotta m1nch1a m1nchia m1st mam0n mamahuev0 mamahuevo mamon masturbat10n masturbat1on masturbate masturbati0n masturbation merd0s0 merd0so merda merde merdos0 merdoso mierda mign0tta mignotta minch1a minchia mist musch1 muschi n1gger neger negr0 negre negro nerch1a nerchia nigger orgasm p00p p011a p01la p0l1a p0lla p0mp1n0 p0mp1no p0mpin0 p0mpino p0op p0rca p0rn p0rra p0uff1asse p0uffiasse p1p1 p1pi p1r1a p1rla p1sc10 p1sc1o p1sci0 p1scio p1sser pa11e pa1le pal1e palle pane1e1r0 pane1e1ro pane1eir0 pane1eiro panele1r0 panele1ro paneleir0 paneleiro patakha pec0r1na pec0rina pecor1na pecorina pen1s pendej0 pendejo penis pip1 pipi pir1a pirla pisc10 pisc1o pisci0 piscio pisser po0p po11a po1la pol1a polla pomp1n0 pomp1no pompin0 pompino poop porca porn porra pouff1asse pouffiasse pr1ck prick pussy put1za puta puta1n putain pute putiza puttana queca r0mp1ba11e r0mp1ba1le r0mp1bal1e r0mp1balle r0mpiba11e r0mpiba1le r0mpibal1e r0mpiballe rand1 randi rape recch10ne recch1one recchi0ne recchione retard romp1ba11e romp1ba1le romp1bal1e romp1balle rompiba11e rompiba1le rompibal1e rompiballe ruff1an0 ruff1ano ruffian0 ruffiano s1ut sa10pe sa1aud sa1ope sacanagem sal0pe salaud salope saugnapf sb0rr0ne sb0rra sb0rrone sbattere sbatters1 sbattersi sborr0ne sborra sborrone sc0pare sc0pata sch1ampe sche1se sche1sse scheise scheisse schlampe schwachs1nn1g schwachs1nnig schwachsinn1g schwachsinnig schwanz scopare scopata sexy sh1t shit slut sp0mp1nare sp0mpinare spomp1nare spompinare str0nz0 str0nza str0nzo stronz0 stronza stronzo stup1d stupid succh1am1 succh1ami succhiam1 succhiami sucker t0pa tapette test1c1e test1cle testic1e testicle tette topa tr01a tr0ia tr0mbare tr1ng1er tr1ngler tring1er tringler tro1a troia trombare turd twat vaffancu10 vaffancu1o vaffancul0 vaffanculo vag1na vagina verdammt verga w1chsen wank wichsen x0ch0ta x0chota xana xoch0ta xochota z0cc01a z0cc0la z0cco1a z0ccola z1z1 z1zi ziz1 zizi zocc01a zocc0la zocco1a zoccola].freeze
MAX_INT =

Maximum integer value that can be encoded Uses Integer::MAX if available (Ruby 2.4+), otherwise calculates the max fixnum value based on the platform’s word size

defined?(Integer::MAX) ? Integer::MAX : ((2**((0.size * 8) - 2)) - 1)

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ MySqids

Initializes a new MySqids encoder with custom options

Parameters:

  • options (Hash) (defaults to: {}) —

    Configuration options

Options Hash (options):

  • :alphabet (String, Array<String>) —

    Custom alphabet to use for encoding (default: DEFAULT_ALPHABET). Must be at least 3 characters and contain only single-byte chars.

  • :min_length (Integer) —

    Minimum length for generated IDs (default: 0). IDs shorter than this will be padded. Must be between 0 and 255.

  • :blocklist (Array<String>, Set<String>) —

    Words to exclude from generated IDs (default: DEFAULT_BLOCKLIST). Words must be at least 3 characters long.

Raises:

  • (ArgumentError) —

    If alphabet contains multibyte characters

  • (ArgumentError) —

    If alphabet is shorter than 3 characters

  • (ArgumentError) —

    If alphabet contains duplicate characters

  • (TypeError) —

    If min_length is not between 0 and 255



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/encoded_id/encoders/my_sqids.rb', line 62

def initialize(options = {})
  alphabet = options[:alphabet] || DEFAULT_ALPHABET
  min_length = options[:min_length] || DEFAULT_MIN_LENGTH
  blocklist = options[:blocklist] || DEFAULT_BLOCKLIST

  raise ArgumentError, "Alphabet cannot contain multibyte characters" if contains_multibyte_chars?(alphabet)
  raise ArgumentError, "Alphabet length must be at least 3" if alphabet.length < 3

  alphabet = alphabet.chars unless alphabet.is_a?(Array)

  if alphabet.uniq.size != alphabet.length
    raise ArgumentError,
      "Alphabet must contain unique characters"
  end

  min_length_limit = 255
  unless min_length.is_a?(Integer) && min_length >= 0 && min_length <= min_length_limit
    raise TypeError,
      "Minimum length has to be between 0 and #{min_length_limit}"
  end

  filtered_blocklist = if options[:blocklist].nil? && options[:alphabet].nil?
    blocklist
  else
    downcased_alphabet = alphabet.map(&:downcase)
    blocklist.select do |word|
      word.length >= 3 && (word.downcase.chars - downcased_alphabet).empty?
    end.to_set(&:downcase)
  end

  @alphabet = shuffle(alphabet.map(&:ord))
  @min_length = min_length
  @blocklist = filtered_blocklist
end

Class Method Details

.max_value ⇒ Object

Returns the maximum integer value that can be safely encoded



42
43
44
 
# File 'lib/encoded_id/encoders/my_sqids.rb', line 42

def self.max_value
  MAX_INT
end

Instance Method Details

#decode(id) ⇒ Array<Integer>

Decodes a Sqids string back into the original array of integers

The decoding process mirrors the encoding:

  1. Validates all characters exist in the alphabet

  2. Extracts the prefix to determine the alphabet offset

  3. Rotates and reverses the alphabet based on the offset

  4. Splits the ID by separator characters (first char of shuffled alphabet)

  5. Converts each chunk back to its original number

  6. Re-shuffles the alphabet between chunks

Examples:

sqids.decode("86Rf07")  # => [1, 2, 3]
sqids.decode("")        # => []
sqids.decode("xyz")     # => [] (if 'xyz' contains invalid chars)

Parameters:

  • id (String) —

    The Sqids string to decode

Returns:

  • (Array<Integer>) —

    Array of integers that were encoded, or empty array if invalid



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/encoded_id/encoders/my_sqids.rb', line 151

def decode(id)
  ret = [] #: Array[Integer]

  return ret if id.empty?

  id = id.codepoints

  # Validate that all characters in the ID exist in our alphabet
  # If any character is invalid, return empty array
  id.each do |c|
    return ret unless @alphabet.include?(c)
  end

  # Extract the prefix (first character) which determines the alphabet transformation
  prefix = id[0]
  offset = @alphabet.index(prefix)
  # If prefix not found in alphabet, return empty (should never happen after validation)
  return [] if offset.nil?

  # Reconstruct the alphabet used during encoding
  alphabet = rotate_and_reverse_alphabet(@alphabet, offset)

  # Remove the prefix, leaving only the encoded number segments
  id = id[1, id.length] || [] #: Array[Integer]

  # Decode each segment separated by the separator character
  while id.length.positive?
    separator = alphabet[0]
    chunks = split_array(id, separator)
    if chunks.any?
      # Empty chunk indicates invalid ID structure
      return ret if chunks[0] == []

      # Convert the chunk back to its original number
      ret.push(to_number(chunks[0], alphabet))
      # Re-shuffle alphabet before processing next segment (matches encoding)
      alphabet = shuffle(alphabet) if chunks.length > 1
    end

    # Continue with the next segment, or empty array if no more segments
    id = (chunks.length > 1) ? chunks[1] : []
  end

  ret
end

#encode(numbers) ⇒ String

Encodes an array of integers into a single Sqids string

The encoding process:

  1. Validates all numbers are in valid range (0 to MAX_INT)

  2. Generates a prefix character based on the numbers and alphabet

  3. Encodes each number using a shuffled alphabet

  4. Separates encoded numbers with the first character of the shuffled alphabet

  5. Pads the result if it’s shorter than min_length

  6. Regenerates if the result contains blocklisted words

Examples:

sqids.encode([1, 2, 3])  # => "86Rf07"
sqids.encode([])         # => ""

Parameters:

  • numbers (Array<Integer>) —

    Array of non-negative integers to encode

Returns:

  • (String) —

    The encoded Sqids string

Raises:

  • (ArgumentError) —

    If any number is outside the valid range (0 to MAX_INT)



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/encoded_id/encoders/my_sqids.rb', line 116

def encode(numbers)
  return "" if numbers.empty?

  # Validate that all numbers are within the acceptable range
  in_range_numbers = numbers.filter_map { |n|
    i = n.to_i
    i if i.between?(0, MAX_INT)
  }
  unless in_range_numbers.length == numbers.length
    raise ArgumentError,
      "Encoding supports numbers between 0 and #{MAX_INT}"
  end

  encode_numbers(in_range_numbers)
end