encoded_id 1.0.0.rc5 → 1.0.0.rc7

data/lib/encoded_id/hex_representation.rb

@@ -1,15 +1,26 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module EncodedId
+  # @rbs!
+  #   type encodeableHexValue = Array[String] | String
+
   class HexRepresentation
+    # @rbs @hex_digit_encoding_group_size: Integer
+    # @rbs @hex_string_separator: Integer
+
+    # @rbs (Integer hex_digit_encoding_group_size) -> void
     def initialize(hex_digit_encoding_group_size)
       @hex_digit_encoding_group_size = validate_hex_digit_encoding_group_size(hex_digit_encoding_group_size)
     end
 
+    # @rbs (encodeableHexValue hexs) -> Array[Integer]
     def hex_as_integers(hexs)
       integer_representation(hexs)
     end
 
+    # @rbs (Array[Integer] integers) -> Array[String]
     def integers_as_hex(integers)
       integers_to_hex_strings(integers)
     end
@@ -18,6 +29,7 @@ module EncodedId
 
     # Number of hex digits to encode in each group, larger values will result in shorter hashes for longer inputs.
     # Vice versa for smaller values, ie a smaller value will result in smaller hashes for small inputs.
+    # @rbs (Integer hex_digit_encoding_group_size) -> Integer
     def validate_hex_digit_encoding_group_size(hex_digit_encoding_group_size)
       if !hex_digit_encoding_group_size.is_a?(Integer) || hex_digit_encoding_group_size < 1 || hex_digit_encoding_group_size > 32
         raise InvalidConfigurationError, "hex_digit_encoding_group_size must be > 0 and <= 32"
@@ -25,25 +37,24 @@ module EncodedId
       hex_digit_encoding_group_size
     end
 
-    # Convert hex strings to integer representations
+    # @rbs (encodeableHexValue hexs) -> Array[Integer]
     def integer_representation(hexs)
       inputs = Array(hexs).map(&:to_s)
-      digits_to_encode = []
+      digits_to_encode = [] #: Array[Integer]
 
       inputs.map { |hex_string| hex_string_as_integer_representation(hex_string) }.each do |integer_groups|
         digits_to_encode.concat(integer_groups)
         digits_to_encode << hex_string_separator
       end
 
-      # Remove the last marker
       digits_to_encode.pop unless digits_to_encode.empty?
       digits_to_encode
     end
 
-    # Convert integer representations to hex strings
+    # @rbs (Array[Integer] integers) -> Array[String]
     def integers_to_hex_strings(integers)
-      hex_strings = []
-      hex_string = []
+      hex_strings = [] #: Array[String]
+      hex_string = [] #: Array[String]
       add_leading = false
 
       integers.reverse_each do |integer|
@@ -52,38 +63,42 @@ module EncodedId
           hex_string = []
           add_leading = false
         else
+          # Add leading zeros to maintain group size for all groups except the first
           hex_string << (add_leading ? "%.#{@hex_digit_encoding_group_size}x" % integer : integer.to_s(16))
           add_leading = true
         end
       end
 
-      # Add the last hex string
       hex_strings << hex_string.join unless hex_string.empty?
       hex_strings.reverse
     end
 
+    # @rbs (String hex_string) -> Array[Integer]
     def hex_string_as_integer_representation(hex_string)
       cleaned = remove_non_hex_characters(hex_string)
       convert_to_integer_groups(cleaned)
     end
 
     # Marker to separate hex strings, must be greater than largest value encoded
+    # @rbs return: Integer
     def hex_string_separator
-      @hex_string_separator ||= 2.pow(@hex_digit_encoding_group_size * 4)
+      @hex_string_separator ||= 2.pow(@hex_digit_encoding_group_size * 4).to_i
     end
 
+    # @rbs (String hex_string) -> String
     def remove_non_hex_characters(hex_string)
       hex_string.gsub(/[^0-9a-f]/i, "")
     end
 
+    # @rbs (String hex_string_cleaned) -> Array[Integer]
     def convert_to_integer_groups(hex_string_cleaned)
-      groups = []
-      hex_string_cleaned.chars.reverse.each_with_index do |char, i|
-        group_id = i / @hex_digit_encoding_group_size
-        groups[group_id] ||= []
-        groups[group_id].unshift(char)
+      groups = [] #: Array[Array[String]]
+      hex_string_cleaned.chars.reverse.each_with_index do |char, index|
+        group_id = index / @hex_digit_encoding_group_size
+        group = (groups[group_id] ||= [])
+        group.unshift(char)
       end
-      groups.map { |c| c.join.to_i(16) }
+      groups.map { _1.join.to_i(16) }
     end
   end
 end

data/lib/encoded_id/reversible_id.rb

@@ -1,144 +1,177 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 # Hashid with a reduced character set Crockford alphabet and split groups
 # See: https://www.crockford.com/wrmg/base32.html
-# Build with https://hashids.org
-# Note hashIds already has a built in profanity limitation algorithm
+# Build with support for https://hashids.org and https://sqids.org
 module EncodedId
+  # @rbs!
+  #   type encodeableValue = Array[String | Integer] | String | Integer
+
   class ReversibleId
-    def initialize(salt:, length: 8, split_at: 4, split_with: "-", alphabet: Alphabet.modified_crockford, hex_digit_encoding_group_size: 4, max_length: 128, max_inputs_per_id: 32)
-      @alphabet = validate_alphabet(alphabet)
-      @salt = validate_salt(salt)
-      @length = validate_length(length)
-      @split_at = validate_split_at(split_at)
-      @split_with = validate_split_with(split_with, alphabet)
-      @hex_represention_encoder = HexRepresentation.new(hex_digit_encoding_group_size)
-      @max_length = validate_max_length(max_length)
-      @max_inputs_per_id = validate_max_input(max_inputs_per_id)
+    # @rbs @config: Encoders::BaseConfiguration
+    # @rbs @hex_represention_encoder: HexRepresentation
+    # @rbs @encoder: untyped
+
+    # Factory method to create a Hashid-based reversible ID
+    # @rbs (salt: String, **untyped options) -> ReversibleId
+    def self.hashid(salt:, **options)
+      new(Encoders::HashidConfiguration.new(salt: salt, **options))
     end
 
-    # Encode the input values into a hash
-    def encode(values)
-      inputs = prepare_input(values)
-      encoded_id = encoded_id_generator.encode(inputs)
-      encoded_id = humanize_length(encoded_id) unless split_with.nil? || split_at.nil?
+    # Factory method to create a Sqids-based reversible ID (default)
+    # @rbs (**untyped options) -> ReversibleId
+    def self.sqids(**options)
+      new(Encoders::SqidsConfiguration.new(**options))
+    end
 
-      raise EncodedIdLengthError if max_length_exceeded?(encoded_id)
+    # Initialize with a configuration object
+    # Defaults to Sqids configuration if called with no arguments
+    # @rbs (?Encoders::BaseConfiguration? config) -> void
+    def initialize(config = nil)
+      @config = config || Encoders::SqidsConfiguration.new
 
-      encoded_id
+      unless @config.is_a?(Encoders::BaseConfiguration)
+        raise InvalidConfigurationError, "config must be an instance of Encoders::BaseConfiguration (or nil for default Sqids)"
+      end
+
+      @hex_represention_encoder = HexRepresentation.new(@config.hex_digit_encoding_group_size)
+      @encoder = create_encoder
     end
 
-    # Encode hex strings into a hash
-    def encode_hex(hexs)
-      encode(hex_represention_encoder.hex_as_integers(hexs))
+    # @rbs () -> String?
+    def salt
+      config = @config
+      return config.salt if config.is_a?(Encoders::HashidConfiguration)
+      nil
     end
 
-    # Decode the hash to original array
-    def decode(str, downcase: true)
-      raise EncodedIdFormatError, "Max length of input exceeded" if max_length_exceeded?(str)
+    def min_length
+      @config.min_length
+    end
 
-      encoded_id_generator.decode(convert_to_hash(str, downcase))
-    rescue InvalidInputError => e
-      raise EncodedIdFormatError, e.message
+    def alphabet
+      @config.alphabet
     end
 
-    # Decode hex strings from a hash
-    def decode_hex(str, downcase: true)
-      integers = encoded_id_generator.decode(convert_to_hash(str, downcase))
-      hex_represention_encoder.integers_as_hex(integers)
+    def split_at
+      @config.split_at
     end
 
-    private
+    def split_with
+      @config.split_with
+    end
 
-    attr_reader :salt,
-      :length,
-      :alphabet,
-      :split_at,
-      :split_with,
-      :hex_represention_encoder,
-      :max_length
+    attr_reader :hex_represention_encoder
 
-    def validate_alphabet(alphabet)
-      return alphabet if alphabet.is_a?(Alphabet)
-      raise InvalidAlphabetError, "alphabet must be an instance of Alphabet"
+    def max_length
+      @config.max_length
     end
 
-    def validate_salt(salt)
-      return salt if salt.is_a?(String) && salt.size > 3
-      raise InvalidConfigurationError, "Salt must be a string and longer than 3 characters"
+    def blocklist
+      @config.blocklist
     end
 
-    # Target length of the encoded string (the minimum but not maximum length)
-    def validate_length(length)
-      return length if valid_integer_option?(length)
-      raise InvalidConfigurationError, "Length must be an integer greater than 0"
-    end
+    attr_reader :encoder #: untyped
 
-    def validate_max_length(max_length)
-      return max_length if valid_integer_option?(max_length) || max_length.nil?
-      raise InvalidConfigurationError, "Max length must be an integer greater than 0"
-    end
+    # Encode the input values into a hash
+    # @rbs (encodeableValue values) -> String
+    def encode(values)
+      inputs = prepare_input(values)
+      encoded_id = encoder.encode(inputs)
+      encoded_id = humanize_length(encoded_id) if @config.split_with && @config.split_at
+
+      raise EncodedIdLengthError if max_length_exceeded?(encoded_id)
 
-    def validate_max_input(max_inputs_per_id)
-      return max_inputs_per_id if valid_integer_option?(max_inputs_per_id)
-      raise InvalidConfigurationError, "Max inputs per ID must be an integer greater than 0"
+      encoded_id
     end
 
-    # Split the encoded string into groups of this size
-    def validate_split_at(split_at)
-      return split_at if valid_integer_option?(split_at) || split_at.nil?
-      raise InvalidConfigurationError, "Split at must be an integer greater than 0 or nil"
+    # Encode hex strings into a hash
+    # @rbs (encodeableHexValue hexs) -> String
+    def encode_hex(hexs)
+      encode(@hex_represention_encoder.hex_as_integers(hexs))
     end
 
-    def validate_split_with(split_with, alphabet)
-      return split_with if split_with.nil? || (split_with.is_a?(String) && !alphabet.characters.include?(split_with))
-      raise InvalidConfigurationError, "Split with must be a string and not part of the alphabet or nil"
+    # Decode the hash to original array
+    # @rbs (String str, ?downcase: bool) -> Array[Integer]
+    def decode(str, downcase: false)
+      raise EncodedIdFormatError, "Max length of input exceeded" if max_length_exceeded?(str)
+
+      encoder.decode(convert_to_hash(str, downcase))
+    rescue InvalidInputError => error
+      raise EncodedIdFormatError, error.message
     end
 
-    def valid_integer_option?(value)
-      value.is_a?(Integer) && value > 0
+    # Decode hex strings from a hash
+    # @rbs (String str, ?downcase: bool) -> Array[String]
+    def decode_hex(str, downcase: false)
+      integers = encoder.decode(convert_to_hash(str, downcase))
+      @hex_represention_encoder.integers_as_hex(integers)
     end
 
+    private
+
+    # @rbs (encodeableValue value) -> Array[Integer]
     def prepare_input(value)
       inputs = value.is_a?(Array) ? value.map(&:to_i) : [value.to_i]
+      raise ::EncodedId::InvalidInputError, "Cannot encode an empty array" if inputs.empty?
       raise ::EncodedId::InvalidInputError, "Integer IDs to be encoded can only be positive" if inputs.any?(&:negative?)
-
-      raise ::EncodedId::InvalidInputError, "%d integer IDs provided, maximum amount of IDs is %d" % [inputs.length, @max_inputs_per_id] if inputs.length > @max_inputs_per_id
+      raise ::EncodedId::InvalidInputError, "%d integer IDs provided, maximum amount of IDs is %d" % [inputs.length, @config.max_inputs_per_id] if inputs.length > @config.max_inputs_per_id
 
       inputs
     end
 
-    def encoded_id_generator
-      @encoded_id_generator ||= HashId.new(salt, length, alphabet)
-    end
-
-    def split_regex
-      @split_regex ||= /.{#{split_at}}(?=.)/
+    # @rbs () -> untyped
+    def create_encoder
+      @config.create_encoder
     end
 
+    # Splits long encoded strings into groups for readability
+    # e.g., "ABCDEFGH" with split_at=4, split_with="-" becomes "ABCD-EFGH"
+    # @rbs (String hash) -> String
     def humanize_length(hash)
-      hash.gsub(split_regex, "\\0#{split_with}")
+      len = hash.length
+      at = @config.split_at #: Integer
+      with = @config.split_with #: String
+      return hash if len <= at
+
+      separator_count = (len - 1) / at
+      result = hash.dup
+      insert_offset = 0
+      (1..separator_count).each do |separator_index|
+        insert_pos = separator_index * at + insert_offset
+        result.insert(insert_pos, with)
+        insert_offset += with.length
+      end
+      result
     end
 
+    # Reverses humanize_length transformation: removes separators and optionally downcases
+    # @rbs (String str, bool downcase) -> String
     def convert_to_hash(str, downcase)
-      clean = str.gsub(split_with, "")
-      clean = clean.downcase if downcase
-      map_equivalent_characters(clean)
+      str = str.gsub(@config.split_with, "") if @config.split_with
+      str = str.downcase if downcase
+      map_equivalent_characters(str)
     end
 
+    # Maps equivalent characters based on alphabet configuration (e.g., 'O' -> '0', 'I' -> '1')
+    # @rbs (String str) -> String
     def map_equivalent_characters(str)
-      return str unless alphabet.equivalences
+      equivalences = @config.alphabet.equivalences
+      return str unless equivalences
 
-      alphabet.equivalences.reduce(str) do |cleaned, ceq|
+      equivalences.reduce(str) do |cleaned, ceq|
         from, to = ceq
         cleaned.tr(from, to)
       end
     end
 
+    # @rbs (String str) -> bool
     def max_length_exceeded?(str)
-      return false if max_length.nil?
+      return false if @config.max_length.nil?
 
-      str.length > max_length
+      str.length > @config.max_length
     end
   end
 end

data/lib/encoded_id/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module EncodedId
-  VERSION = "1.0.0.rc5"
+  VERSION = "1.0.0.rc7"
 end

data/lib/encoded_id.rb

@@ -1,26 +1,56 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 require_relative "encoded_id/version"
 require_relative "encoded_id/alphabet"
 require_relative "encoded_id/hex_representation"
+require_relative "encoded_id/blocklist"
+
+# Load the encoder framework
+require_relative "encoded_id/encoders/hashid_salt"
+require_relative "encoded_id/encoders/hashid_consistent_shuffle"
+require_relative "encoded_id/encoders/hashid_ordinal_alphabet_separator_guards"
+require_relative "encoded_id/encoders/hashid"
+
+require "sqids"
+# TODO: move back to only using gem once upstreamed our changes
+require_relative "encoded_id/encoders/my_sqids"
+require_relative "encoded_id/encoders/sqids_with_blocklist_mode"
 
-require_relative "encoded_id/hash_id_salt"
-require_relative "encoded_id/hash_id_consistent_shuffle"
-require_relative "encoded_id/ordinal_alphabet_separator_guards"
-require_relative "encoded_id/hash_id"
+require_relative "encoded_id/encoders/sqids"
+
+# Load configuration classes
+require_relative "encoded_id/encoders/base_configuration"
+require_relative "encoded_id/encoders/hashid_configuration"
+require_relative "encoded_id/encoders/sqids_configuration"
 
 require_relative "encoded_id/reversible_id"
 
+# @rbs!
+#   module Sqids
+#     DEFAULT_BLOCKLIST: Array[String]
+#   end
+
 module EncodedId
+  # @rbs InvalidConfigurationError: singleton(StandardError)
   class InvalidConfigurationError < StandardError; end
 
+  # @rbs InvalidAlphabetError: singleton(ArgumentError)
   class InvalidAlphabetError < ArgumentError; end
 
+  # @rbs EncodedIdFormatError: singleton(ArgumentError)
   class EncodedIdFormatError < ArgumentError; end
 
+  # @rbs EncodedIdLengthError: singleton(ArgumentError)
   class EncodedIdLengthError < ArgumentError; end
 
+  # @rbs InvalidInputError: singleton(ArgumentError)
   class InvalidInputError < ArgumentError; end
 
+  # @rbs BlocklistError: singleton(StandardError)
+  class BlocklistError < StandardError; end
+
+  # @rbs SaltError: singleton(ArgumentError)
   class SaltError < ArgumentError; end
 end

metadata

@@ -1,74 +1,82 @@
 --- !ruby/object:Gem::Specification
 name: encoded_id
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc5
+  version: 1.0.0.rc7
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+date: 2025-11-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sqids
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 description: Encode your numerical IDs (eg record primary keys) into obfuscated strings
   that can be used in URLs. The obfuscated strings are reversible, so you can decode
   them back into the original numerical IDs. Supports encoding multiple IDs at once,
   and generating IDs with custom alphabets and separators to make the IDs easier to
-  read or share. Dependency free.
+  read or share. Uses Sqids by default, with HashIds as an alternative.
 email:
 - stevegeek@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".devcontainer/Dockerfile"
-- ".devcontainer/compose.yml"
-- ".devcontainer/devcontainer.json"
-- ".standard.yml"
 - CHANGELOG.md
-- Gemfile
 - LICENSE.txt
 - README.md
-- Rakefile
-- Steepfile
-- ext/encoded_id/extconf.rb
-- ext/encoded_id/extension.c
-- ext/encoded_id/hashids.c
-- ext/encoded_id/hashids.h
+- context/encoded_id.md
 - lib/encoded_id.rb
 - lib/encoded_id/alphabet.rb
-- lib/encoded_id/hash_id.rb
-- lib/encoded_id/hash_id_consistent_shuffle.rb
-- lib/encoded_id/hash_id_salt.rb
+- lib/encoded_id/blocklist.rb
+- lib/encoded_id/encoders/base_configuration.rb
+- lib/encoded_id/encoders/hashid.rb
+- lib/encoded_id/encoders/hashid_configuration.rb
+- lib/encoded_id/encoders/hashid_consistent_shuffle.rb
+- lib/encoded_id/encoders/hashid_ordinal_alphabet_separator_guards.rb
+- lib/encoded_id/encoders/hashid_salt.rb
+- lib/encoded_id/encoders/my_sqids.rb
+- lib/encoded_id/encoders/sqids.rb
+- lib/encoded_id/encoders/sqids_configuration.rb
+- lib/encoded_id/encoders/sqids_with_blocklist_mode.rb
 - lib/encoded_id/hex_representation.rb
-- lib/encoded_id/ordinal_alphabet_separator_guards.rb
 - lib/encoded_id/reversible_id.rb
 - lib/encoded_id/version.rb
-- rbs_collection.yaml
-- sig/encoded_id.rbs
 homepage: https://github.com/stevegeek/encoded_id
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/stevegeek/encoded_id
   source_code_uri: https://github.com/stevegeek/encoded_id
-  changelog_uri: https://github.com/stevegeek/encoded_id/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/stevegeek/encoded_id/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
-- ext
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.2
 specification_version: 4
 summary: EncodedId is a gem for creating reversible obfuscated IDs from numerical
-  IDs. It uses an implementation of Hash IDs under the hood.
+  IDs. It uses Sqids by default.
 test_files: []

data/.devcontainer/Dockerfile

@@ -1,9 +0,0 @@
-# Make sure RUBY_VERSION matches the Ruby version in .ruby-version or gemspec
-ARG RUBY_VERSION=3.4.2
-FROM ghcr.io/rails/devcontainer/images/ruby:$RUBY_VERSION
-
-USER vscode
-
-# Ensure binding is always 0.0.0.0
-# Binds the server to all IP addresses of the container, so it can be accessed from outside the container.
-ENV BINDING="0.0.0.0"

data/.devcontainer/compose.yml

@@ -1,8 +0,0 @@
-name: "encoded_id"
-
-services:
-  encoded-id-dev-env:
-    container_name: encoded-id-dev-env
-    build:
-      context: ..
-      dockerfile: .devcontainer/Dockerfile

data/.devcontainer/devcontainer.json

@@ -1,8 +0,0 @@
-{
-  "name": "Encoded ID Gem Development",
-  "dockerComposeFile": "compose.yml",
-  "service": "encoded-id-dev-env",
-  "postCreateCommand": "bundle install",
-  "postStartCommand": "bundle exec rake test",
-  "remoteUser": "vscode"
-}

data/.standard.yml

@@ -1,2 +0,0 @@
-parallel: true          # default: false
-ruby_version: 3.3

data/Gemfile

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in encoded_id.gemspec
-gemspec
-
-gem "rake"
-
-gem "minitest"
-
-gem "standard"
-
-# gem "rbs"
-#
-# gem "steep"
-
-gem "simplecov"
-
-gem "benchmark-ips"
-
-gem "benchmark-memory"
-
-gem "fuzzbert"
-
-gem "singed"
-
-gem "memory_profiler"
-
-gem "hashids" # For benchmarking against
-
-gem "base64"
-
-# gem "pf2", require: false, github: "osyoyu/pf2", branch: "main"
-
-# gem "vernier", require: false

data/Rakefile

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rake/testtask"
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/test_*.rb"]
-end
-
-task default: %i[test standard]
-
-task :compile_ext do
-  puts "Compiling extension"
-  `cd ext/encoded_id && make clean`
-  `cd ext/encoded_id && ruby extconf.rb`
-  `cd ext/encoded_id && make`
-  puts "Done"
-end

data/Steepfile

@@ -1,5 +0,0 @@
-target :lib do
-  signature "sig"
-
-  check "lib"
-end

data/ext/encoded_id/extconf.rb

@@ -1,3 +0,0 @@
-require "mkmf"
-
-create_makefile "encoded_id/extension"