encoded_id 1.0.0.rc5 → 1.0.0.rc6

data/lib/encoded_id/reversible_id.rb

@@ -1,12 +1,33 @@
 # 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)
+    # @rbs VALID_ENCODERS: Array[Symbol]
+    VALID_ENCODERS = [:hashids, :sqids].freeze
+    # @rbs DEFAULT_ENCODER: Symbol
+    DEFAULT_ENCODER = :hashids
+
+    # @rbs @alphabet: Alphabet
+    # @rbs @salt: String
+    # @rbs @length: Integer
+    # @rbs @split_at: Integer?
+    # @rbs @split_with: String?
+    # @rbs @hex_represention_encoder: HexRepresentation
+    # @rbs @max_length: Integer?
+    # @rbs @max_inputs_per_id: Integer
+    # @rbs @blocklist: Blocklist
+    # @rbs @encoder: Encoders::Base
+
+    # @rbs (salt: String, ?length: Integer, ?split_at: Integer?, ?split_with: String?, ?alphabet: Alphabet, ?hex_digit_encoding_group_size: Integer, ?max_length: Integer?, ?max_inputs_per_id: Integer, ?encoder: Symbol | Encoders::Base, ?blocklist: Blocklist | Array[String] | Set[String] | nil) -> void
+    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, encoder: DEFAULT_ENCODER, blocklist: Blocklist.empty)
       @alphabet = validate_alphabet(alphabet)
       @salt = validate_salt(salt)
       @length = validate_length(length)
@@ -15,13 +36,27 @@ module EncodedId
       @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)
+      @blocklist = validate_blocklist(blocklist)
+      @encoder = create_encoder(validate_encoder(encoder))
     end
 
+    # Accessors for introspection
+    attr_reader :salt #: String
+    attr_reader :length #: Integer
+    attr_reader :alphabet #: Alphabet
+    attr_reader :split_at #: Integer?
+    attr_reader :split_with #: String?
+    attr_reader :hex_represention_encoder #: HexRepresentation
+    attr_reader :max_length #: Integer?
+    attr_reader :blocklist #: Blocklist
+    attr_reader :encoder #: Encoders::Base
+
     # Encode the input values into a hash
+    # @rbs (encodeableValue values) -> String
     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?
+      encoded_id = encoder.encode(inputs)
+      encoded_id = humanize_length(encoded_id) if split_with && split_at
 
       raise EncodedIdLengthError if max_length_exceeded?(encoded_id)
 
@@ -29,78 +64,83 @@ module EncodedId
     end
 
     # Encode hex strings into a hash
+    # @rbs (encodeableHexValue hexs) -> String
     def encode_hex(hexs)
       encode(hex_represention_encoder.hex_as_integers(hexs))
     end
 
     # Decode the hash to original array
+    # @rbs (String str, ?downcase: bool) -> Array[Integer]
     def decode(str, downcase: true)
       raise EncodedIdFormatError, "Max length of input exceeded" if max_length_exceeded?(str)
 
-      encoded_id_generator.decode(convert_to_hash(str, downcase))
+      encoder.decode(convert_to_hash(str, downcase))
     rescue InvalidInputError => e
       raise EncodedIdFormatError, e.message
     end
 
     # Decode hex strings from a hash
+    # @rbs (String str, ?downcase: bool) -> Array[String]
     def decode_hex(str, downcase: true)
-      integers = encoded_id_generator.decode(convert_to_hash(str, downcase))
+      integers = encoder.decode(convert_to_hash(str, downcase))
       hex_represention_encoder.integers_as_hex(integers)
     end
 
     private
 
-    attr_reader :salt,
-      :length,
-      :alphabet,
-      :split_at,
-      :split_with,
-      :hex_represention_encoder,
-      :max_length
-
+    # @rbs (Alphabet alphabet) -> Alphabet
     def validate_alphabet(alphabet)
       return alphabet if alphabet.is_a?(Alphabet)
       raise InvalidAlphabetError, "alphabet must be an instance of Alphabet"
     end
 
+    # @rbs (String salt) -> String
     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"
     end
 
     # Target length of the encoded string (the minimum but not maximum length)
+    # @rbs (Integer length) -> Integer
     def validate_length(length)
       return length if valid_integer_option?(length)
       raise InvalidConfigurationError, "Length must be an integer greater than 0"
     end
 
+    # @rbs (Integer? max_length) -> Integer?
     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
 
+    # @rbs (Integer max_inputs_per_id) -> Integer
     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"
     end
 
     # Split the encoded string into groups of this size
+    # @rbs (Integer? split_at) -> Integer?
     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"
     end
 
+    # @rbs (String? split_with, Alphabet alphabet) -> String?
     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"
     end
 
+    # @rbs (Integer? value) -> bool
     def valid_integer_option?(value)
       value.is_a?(Integer) && value > 0
     end
 
+    # @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
@@ -108,24 +148,69 @@ module EncodedId
       inputs
     end
 
-    def encoded_id_generator
-      @encoded_id_generator ||= HashId.new(salt, length, alphabet)
+    # @rbs (Symbol | Encoders::Base encoder) -> Encoders::Base
+    def create_encoder(encoder)
+      # If an encoder instance was provided, return it directly
+      return @encoder if defined?(@encoder) && @encoder.is_a?(Encoders::Base)
+      return encoder if encoder.is_a?(Encoders::Base)
+
+      case encoder
+      when :sqids
+        if defined?(Encoders::Sqids)
+          Encoders::Sqids.new(salt, length, alphabet, @blocklist)
+        else
+          raise InvalidConfigurationError, "Sqids encoder requested but the sqids gem is not available. Please add 'gem \"sqids\"' to your Gemfile."
+        end
+      when :hashids
+        Encoders::HashId.new(salt, length, alphabet, @blocklist)
+      else
+        raise InvalidConfigurationError, "The encoder name is not supported '#{encoder}'"
+      end
+    end
+
+    # @rbs (Symbol | Encoders::Base encoder) -> (Symbol | Encoders::Base)
+    def validate_encoder(encoder)
+      # Accept either a valid symbol or an Encoders::Base instance
+      return encoder if VALID_ENCODERS.include?(encoder) || encoder.is_a?(Encoders::Base)
+      raise InvalidConfigurationError, "Encoder must be one of: #{VALID_ENCODERS.join(", ")} or an instance of EncodedId::Encoders::Base"
     end
 
-    def split_regex
-      @split_regex ||= /.{#{split_at}}(?=.)/
+    # @rbs (Blocklist | Array[String] | Set[String] | nil blocklist) -> Blocklist
+    def validate_blocklist(blocklist)
+      return blocklist if blocklist.is_a?(Blocklist)
+      return Blocklist.empty if blocklist.nil?
+
+      return Blocklist.new(blocklist) if blocklist.is_a?(Array) || blocklist.is_a?(Set)
+
+      raise InvalidConfigurationError, "Blocklist must be an instance of Blocklist, a Set, or an Array of strings"
     end
 
+    # @rbs (String hash) -> String
     def humanize_length(hash)
-      hash.gsub(split_regex, "\\0#{split_with}")
+      len = hash.length
+      at = split_at #: Integer
+      with = split_with #: String
+      return hash if len <= at
+
+      separator_count = (len - 1) / at
+      result = hash.dup
+      insert_offset = 0
+      (1..separator_count).each do |i|
+        insert_pos = i * at + insert_offset
+        result.insert(insert_pos, with)
+        insert_offset += with.length
+      end
+      result
     end
 
+    # @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(split_with, "") if split_with
+      str = str.downcase if downcase
+      map_equivalent_characters(str)
     end
 
+    # @rbs (String str) -> String
     def map_equivalent_characters(str)
       return str unless alphabet.equivalences
 
@@ -135,6 +220,7 @@ module EncodedId
       end
     end
 
+    # @rbs (String str) -> bool
     def max_length_exceeded?(str)
       return false if max_length.nil?
 

data/lib/encoded_id/version.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module EncodedId
-  VERSION = "1.0.0.rc5"
+  # @rbs VERSION: String
+  VERSION = "1.0.0.rc6"
 end

data/lib/encoded_id.rb

@@ -1,26 +1,59 @@
 # 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/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/blocklist"
+
+# Load the encoder framework
+require_relative "encoded_id/encoders/base"
+require_relative "encoded_id/encoders/hash_id_salt"
+require_relative "encoded_id/encoders/hash_id_consistent_shuffle"
+require_relative "encoded_id/encoders/hash_id_ordinal_alphabet_separator_guards"
+require_relative "encoded_id/encoders/hash_id"
+
+# Only load Sqids encoder if the gem is available
+begin
+  require "sqids"
+  require_relative "encoded_id/encoders/my_sqids"
+  require_relative "encoded_id/encoders/sqids"
+rescue LoadError
+  # Sqids gem not available, encoder will not be loaded
+end
 
 require_relative "encoded_id/reversible_id"
 
+# @rbs!
+#   class Integer
+#     MAX: Integer
+#   end
+#
+#   # Optional Sqids gem support
+#   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,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: encoded_id
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc5
+  version: 1.0.0.rc6
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-11-17 00:00:00.000000000 Z
 dependencies: []
 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
@@ -20,54 +20,45 @@ 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.rb
+- lib/encoded_id/encoders/hash_id.rb
+- lib/encoded_id/encoders/hash_id_consistent_shuffle.rb
+- lib/encoded_id/encoders/hash_id_ordinal_alphabet_separator_guards.rb
+- lib/encoded_id/encoders/hash_id_salt.rb
+- lib/encoded_id/encoders/my_sqids.rb
+- lib/encoded_id/encoders/sqids.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.

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"

data/ext/encoded_id/extension.c

@@ -1,123 +0,0 @@
-#include "ruby/ruby.h"
-#include "hashids.h"
-
-void wrapped_hashids_free(void* data)
-{
-    hashids_free(data);
-}
-
-size_t wrapped_hashids_size(const void* data)
-{
-    return sizeof(hashids_t);
-}
-
-static const rb_data_type_t wrapped_hashids_type = {
-    .wrap_struct_name = "hashids_t",
-    .function = {
-        .dmark = NULL,
-        .dfree = wrapped_hashids_free,
-        .dsize = wrapped_hashids_size,
-    },
-    .data = NULL,
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
-};
-
-VALUE hashids_alloc(VALUE self)
-{
-    hashids_t *data = hashids_init("salt!");
-    return TypedData_Wrap_Struct(self, &wrapped_hashids_type, data);
-}
-
-//VALUE rb_hashids_m_initialize(VALUE self, VALUE val)
-//{
-//    return self;
-//}
-
-
-static VALUE rb_hash_id_c_encode(VALUE self, VALUE ids) {
-    Check_Type(ids, T_ARRAY);
-
-    long length = RARRAY_LEN(ids);
-
-    unsigned long long* inputs = ALLOC_N(unsigned long long, length);
-
-    for (long i = 0; i < length; i++) {
-        VALUE rb_element = rb_ary_entry(ids, i);
-        Check_Type(rb_element, T_FIXNUM);
-        inputs[i] = NUM2ULL(rb_element);
-    }
-
-    hashids_t* hashids;
-
-    TypedData_Get_Struct(self, hashids_t, &wrapped_hashids_type, hashids);
-
-    size_t bytes_encoded;
-
-    size_t bytes_needed;
-    bytes_needed = hashids_estimate_encoded_size(hashids, sizeof(&inputs) / sizeof(unsigned long long), &inputs);
-    char *hash = ALLOC_N(char, bytes_needed);
-
-    // unsigned long long numbers[] = {1ull, 2ull, 3ull, 4ull, 5ull};
-
-//    printf("length: %ld\n", length);
-//    printf("inputs[0]: %llu\n", inputs[0]);
-//    printf("inputs[1]: %llu\n", inputs[1]);
-//    printf("inputs[2]: %llu\n", inputs[2]);
-//    printf("inputs[3]: %llu\n", inputs[3]);
-//    printf("inputs[4]: %llu\n", inputs[4]);
-//
-//    printf("hashids: %p\n", hashids);
-//    printf("hashids->alphabet: %s\n", hashids->alphabet);
-//    printf("hashids->salt: %s\n", hashids->salt);
-//    printf("hashids->min_hash_length: %lu\n", hashids->min_hash_length);
-//    printf("numbers: %p\n", numbers);
-//    printf("numbers[0]: %llu\n", numbers[0]);
-//    printf("numbers[1]: %llu\n", numbers[1]);
-//    printf("numbers[2]: %llu\n", numbers[2]);
-//    printf("numbers[3]: %llu\n", numbers[3]);
-//    printf("numbers[4]: %llu\n", numbers[4]);
-//
-//    printf("sizeof(*inputs) / sizeof(unsigned long long): %lu\n", sizeof(*inputs) / sizeof(unsigned long long));
-//    printf("sizeof(numbers) / sizeof(unsigned long long): %lu\n", sizeof(numbers) / sizeof(unsigned long long));
-    // bytes_encoded = hashids_encode(hashids, hash, sizeof(numbers) / sizeof(unsigned long long), numbers);
-    bytes_encoded = hashids_encode(hashids, hash, length, inputs);
-
-    ruby_xfree(inputs);
-    VALUE return_value = rb_str_new2(hash);
-    ruby_xfree(hash);
-    return return_value;
-}
-
-static VALUE rb_hash_id_c_decode(VALUE self, VALUE str) {
-    Check_Type(str, T_STRING);
-
-    hashids_t* hashids;
-
-    TypedData_Get_Struct(self, hashids_t, &wrapped_hashids_type, hashids);
-
-    size_t numbers_count = hashids_numbers_count(hashids, RSTRING_PTR(str));
-
-    unsigned long long* numbers = ALLOC_N(unsigned long long, numbers_count);
-
-    hashids_decode_safe(hashids, RSTRING_PTR(str), numbers, numbers_count);
-
-    VALUE rb_numbers = rb_ary_new_capa(numbers_count);
-
-    for (size_t i = 0; i < numbers_count; i++) {
-        rb_ary_push(rb_numbers, ULL2NUM(numbers[i]));
-    }
-
-    ruby_xfree(numbers);
-    return rb_numbers;
-}
-
-void Init_extension(void) {
-    VALUE EncodedId = rb_define_module("EncodedId");
-    VALUE HashIdC = rb_define_class_under(EncodedId, "HashIdC", rb_cObject);
-
-    rb_define_alloc_func(HashIdC, hashids_alloc);
-//    rb_define_method(HashIdC, "initialize", rb_hashids_m_initialize, 1);
-
-    rb_define_method(HashIdC, "encode", rb_hash_id_c_encode, 1);
-    rb_define_method(HashIdC, "decode", rb_hash_id_c_decode, 1);
-}