encoded_id 1.0.0.rc6 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5135a9e76cfd6a49cd14921bfa277deb83eb05b9e753efdb23e4145b3f5f7c7
-  data.tar.gz: ed8a43d5e654d9fd947d7b9b0a37aacc18c3b713c9303c9d6dbbf22b890eb965
+  metadata.gz: ccfa7987d3a108bfce0268467b8ae40793226e98f01fa2c331bc1f642026f47b
+  data.tar.gz: b4cb2429a8031f0e576f242550397b4683e302a184d57f0c85b870da502e181e
 SHA512:
-  metadata.gz: 91e58ac5b6df75e7da94f8ea4868967e93f6b8c76ec94cb6fc821a60ab33dfe704b19ad43d41916f8896d5db982f6d610e48335f8e9d03129f0422a7b0f5cd60
-  data.tar.gz: f427c6e2ca883e522e80a934053a5b5486dc75be3a6babf5e55f878d85fe8e31a0a1c1af98b4bbda8a5f310be18ac5ea2b2ec8edf322b54584d78b2126c92c15
+  metadata.gz: db4ae0c6d8477ea3ab5ada1bcbd959b18420c1aa1be54ec747898d298f16e6dd6a2090ff4a18008fe1711d3641c158bf9a8c1da23a33663be7fbc17a68079409
+  data.tar.gz: 4e731df7f992cf6935012cabffc7c6d4923de5db46059c123780d0f6a1dfbe329844ddf074580c67ec1a16101afb9c315175049045bcf5375e6666ae2707fa0b

data/CHANGELOG.md

@@ -1,14 +1,39 @@
 ## [Unreleased]
 
-## [2.0.0.alpha1] - unreleased
+- nothing yet
+
+## [1.0.0] - 2025-11-21
+
+- First stable release!
+
+**Important!!: `:sqids` are not compatible with `:hashids`, DO NOT CHANGE FROM ONE TO THE OTHER AFTER GOING LIVE.**
+
+### Fixed (Rails integration)
+
+- Ensure finder methods correctly override their ActiveRecord counterparts 
+- Warn when ActiveRecord integration used in model that doesn't use `id` as primary key
+
+## [1.0.0.rc7] - 2025-11-19
 
 ### Breaking changes
 
-- `ReversibleId` now no longer downcases the encodedid input string by default on decode, ie the `decode` option `downcase` is now `false`. In a future release the `downcase` option will be removed.
-- The default encoding engine is now `:sqids` to reflect the official "deprecated" status of `Hashid`s (see https://sqids.org/faq#why-hashids) 
+- `ReversibleId` now no longer downcases the encodedid input string by default on decode, ie the `decode` option `downcase` is now `false`. This can be configured via the Rails configuration `downcase_on_decode` option.  In a future release the `downcase` option will be removed.
+- The default encoding engine is now `:sqids` to reflect the official "deprecated" status of `Hashid`s (see https://sqids.org/faq#why-hashids)
 - Ruby < 3.2 support dropped. The minimum supported Ruby version is now 3.2.0
+- `Encoders` classes no longer expose `encode_hex` and `decode_hex` as they worked differently to the similarly named methods on ReversibleId
+- Rails generator now needs you to specify which encoding algorithm you are using
 
-**Important!!: `:sqids` are not compatible with `:hashids`, DO NOT CHANGE FROM ONE TO THE OTHER AFTER GOING LIVE.**
+### Added (Rails integration)
+
+- `encoded_id_options` class method to override `encoded_id` configuration on a model by model basis
+- Blocklist application "modes". User can decide if the blocklist checks should be applied in situations 
+  where very long encoded IDs are likely and hence block word collisions are undesirably likely.
+
+### Changed
+
+- Blocklists are now pre-filtered to the encoder alphabet to avoid testing words which cannot be created by that alphabet anyway.
+- Updates to inline RBS type signatures
+- Documentation updates
 
 ## [1.0.0.rc6] - 2025-11-17
 

data/README.md

@@ -7,28 +7,58 @@
 
 `encoded_id-rails` is a Rails integration that provides additional features for using `encoded_id` with ActiveRecord models.
 
+It's one of the most, if not _the_ most, feature complete gem of its kind!
+
 👉 **Full documentation available at [encoded-id.onrender.com](https://encoded-id.onrender.com)**
 
+## Key Features
+
+* 🔄 **Reversible** - Encoded IDs can be decoded back to the original values
+* 👥 **Multiple IDs** - Encode multiple numeric IDs in one string
+* 🚀 **Choose your encoding** - Supports `Sqids` (default) and `Hashids`, or use your own custom encoder
+* 👓 **Human-readable** - Character grouping & character mappings of easily confused characters for better readability
+* 🔡 **Custom alphabets** - Use your preferred character set, or a provided default
+* 🚗 **Performance** - Uses an optimized `Hashids` encoder (compared to `hashids` gem) for better performance and less memory usage, and have pushed performance improvements to `Sqids` as well
+* 🤬 **Blocklist filtering** - Built-in word blocklist support with configurable modes and optional default lists
+
+### Rails Integration Features
+
+* 🏷️ **ActiveRecord integration** - Use with ActiveRecord models
+* 🔑 **Per-model configuration** - Use custom salt and encoding settings per model
+* 💅 **Slugged IDs** - URL-friendly slugs like `my-product--p5w9-z27j`
+* 🔖 **Annotated IDs** - Model type indicators like `user_p5w9-z27j` (default behavior)
+* 🔍 **Finder methods** - `find_by_encoded_id`, `find_by_encoded_id!`, `find_all_by_encoded_id`, `where_encoded_id`
+* 🛣️ **URL params** - `to_param` automatically uses encoded IDs
+* 🔒 **Safe defaults** - Limits on encoded ID lengths to prevent CPU and memory-intensive encode/decodes when used in URLs
+* 💾 **Persistence** - Optional database persistence for efficient lookups
+
+
 ## Quick Example
 
 ```ruby
-coder = ::EncodedId::ReversibleId.new(salt: "my-salt")
+# Using Hashids encoder (requires salt)
+coder = ::EncodedId::ReversibleId.hashid(salt: "my-salt")
 coder.encode(123)
-# => "p5w9-z27j"
+# => "m3pm-8anj"
 
 # The encoded strings are reversible
-coder.decode("p5w9-z27j")
+coder.decode("m3pm-8anj")
 # => [123]
 
 # Supports encoding multiple IDs at once
 coder.encode([78, 45])
-# => "z2j7-0dmw"
+# => "ny9y-sd7p"
+
+# Using Sqids encoder (default, no salt required)
+sqids_coder = ::EncodedId::ReversibleId.sqids
+sqids_coder.encode(123)
+# => (encoded value varies)
 
 # Can also be used with ActiveRecord models
 class User < ApplicationRecord
   include EncodedId::Rails::Model
-  
-  # Optional slug for the encoded ID
+
+  # Optional: define method to provide slug for encoded ID
   def name_for_encoded_id_slug
     full_name
   end
@@ -40,28 +70,6 @@ user.encoded_id                             # => "user_p5w9-z27j"
 user.slugged_encoded_id                     # => "bob-smith--user_p5w9-z27j"
 ```
 
-## Key Features
-
-* 🔄 **Reversible** - Encoded IDs can be decoded back to the original values
-* 👥 **Multiple IDs** - Encode multiple numeric IDs in one string
-* 🚀 **Choose your encoding** - Supports `Hashids` and `Sqids` out of the box, or use your own custom encoder
-* 👓 **Human-readable** - Character grouping & character mappings of easily confused characters for better readability
-* 🔡 **Custom alphabets** - Use your preferred character set, or a provided default
-* 🚗 **Performance** - Uses an optimized `Hashids` encoder (compared to `hashids` gem) for better performance and less memory usage, and have pushed performance improvements to `Sqids` as well
-* 🤬 **Profanity blocking** - Built-in word blocklist support and optional default lists
-
-### Rails Integration Features
-
-* 🏷️ **ActiveRecord integration** - Use with ActiveRecord models
-* 🔑 **Per-model salt** - Use a custom salt for encoding per model
-* 💅 **Slugged IDs** - URL-friendly slugs like `my-product--p5w9-z27j`
-* 🔖 **Annotated IDs** - Model type indicators like `user_p5w9-z27j`
-* 🔍 **Finder methods** - Find records using encoded IDs
-* 🛣️ **URL params** - `to_param` with encoded IDs
-* 🔒 **Safe defaults**: Limits on encoded ID lengths to prevent CPU and memory-intensive encode/decodes eg when used in URLs
-* 💾 **Persistence** - Optional database persistence for efficient lookups
-
-
 ## Standalone Gem
 
 
@@ -91,6 +99,10 @@ See the [Rails Integration](https://encoded-id.onrender.com/docs/encoded_id_rail
 
 **Encoded IDs are not secure**. They are meant to provide obfuscation, not encryption. Do not use them as a security mechanism.
 
+As of version 1.0.0, `Sqids` is the default encoder. `Hashids` is still supported but is officially deprecated by the Hashids project in favor of Sqids.
+
+Read more about the security implications: [Hashids expose salt value](https://www.sjoerdlangkemper.nl/2023/11/25/hashids-expose-salt-value/) (note: this specifically applies to Hashids encoder)
+
 ## Compare to Alternate Gems
 
 - [prefixed_ids](https://github.com/excid3/prefixed_ids)
@@ -105,11 +117,10 @@ For a detailed comparison, see the [Compared to Other Gems](https://encoded-id.o
 
 Visit [encoded-id.onrender.com](https://encoded-id.onrender.com) for comprehensive documentation including:
 
-- [EncodedId Core API](https://encoded-id.onrender.com/docs/encoded_id/api)
-- [Rails Integration API](https://encoded-id.onrender.com/docs/encoded_id_rails/api)
-- [Configuration Options](https://encoded-id.onrender.com/docs/encoded_id/configuration)
-- [Examples](https://encoded-id.onrender.com/docs/encoded_id/examples)
-- [Advanced Topics](https://encoded-id.onrender.com/docs/advanced-topics)
+- [EncodedId Core Guide](https://encoded-id.onrender.com/docs/encoded_id/) - Installation, configuration, examples, and advanced topics
+- [EncodedId Rails Guide](https://encoded-id.onrender.com/docs/encoded_id_rails/) - Rails integration, configuration, and examples
+- [EncodedId Core API Reference](https://encoded-id.onrender.com/docs/encoded_id/api)
+- [Rails Integration API Reference](https://encoded-id.onrender.com/docs/encoded_id_rails/api)
 
 ## Development
 

data/context/encoded_id.md

@@ -14,6 +14,25 @@
 - **Performance Optimized**: Uses an optimized HashIds implementation for better performance
 - **Profanity Protection**: Built-in blocklist support to prevent offensive words in generated IDs
 - **Customizable**: Configurable alphabets, lengths, and formatting options
+- **Blocklist Modes**: Three modes for controlling blocklist checking performance
+
+## Quick Reference
+
+```ruby
+# Sqids encoder (default, no salt required)
+coder = EncodedId::ReversibleId.sqids(min_length: 10)
+id = coder.encode(123)          # => "p5w9-z27j-k8"
+nums = coder.decode(id)         # => [123]
+
+# Hashids encoder (requires salt)
+coder = EncodedId::ReversibleId.hashid(salt: "my-salt", min_length: 8)
+id = coder.encode([78, 45])     # => "z2j7-0dmw"
+nums = coder.decode(id)         # => [78, 45]
+
+# UUID encoding (experimental)
+hex_id = coder.encode_hex("9a566b8b-8618-42ab-8db7-a5a0276401fd")
+uuid = coder.decode_hex(hex_id).first
+```
 
 ## Core API
 
@@ -21,30 +40,65 @@
 
 The main class for encoding and decoding IDs.
 
-#### Constructor
+#### Factory Methods (Recommended)
+
+Factory methods provide the cleanest way to create encoders:
 
 ```ruby
-EncodedId::ReversibleId.new(
-  salt:,                         # Required: String salt (min 4 chars)
-  length: 8,                     # Minimum length of encoded string
+# Sqids encoder (default, no salt required)
+coder = EncodedId::ReversibleId.sqids(
+  min_length: 10,
+  blocklist: ["bad", "words"]
+)
+
+# Hashids encoder (requires salt)
+coder = EncodedId::ReversibleId.hashid(
+  salt: "my-salt",
+  min_length: 8,
+  blocklist: ["bad", "words"]
+)
+```
+
+Both factory methods accept all configuration options described below.
+
+#### Constructor (Alternative)
+
+You can also use the constructor with explicit configuration objects:
+
+```ruby
+# Using Sqids configuration
+config = EncodedId::Encoders::SqidsConfiguration.new(
+  min_length: 8,                 # Minimum length of encoded string
   split_at: 4,                   # Split encoded string every X characters
   split_with: "-",               # Character to split with
   alphabet: EncodedId::Alphabet.modified_crockford,
   hex_digit_encoding_group_size: 4,
   max_length: 128,               # Maximum length limit
   max_inputs_per_id: 32,         # Maximum IDs to encode together
-  encoder: :hashids,             # :hashids or :sqids
-  blocklist: nil                 # Words to prevent in IDs
+  blocklist: nil,                # Words to prevent in IDs
+  blocklist_mode: :length_threshold,  # :always, :length_threshold, or :raise_if_likely
+  blocklist_max_length: 32       # Max length for :length_threshold mode
+)
+coder = EncodedId::ReversibleId.new(config)
+
+# Using Hashids configuration (requires salt)
+config = EncodedId::Encoders::HashidConfiguration.new(
+  salt: "my-salt",               # Required for Hashids (min 4 chars)
+  min_length: 8,
+  # ... other options same as above
 )
+coder = EncodedId::ReversibleId.new(config)
 ```
 
+**Note**: As of v1.0.0, the default encoder is `:sqids`. For backwards compatibility with pre-v1 versions, use `ReversibleId.hashid()`.
+
 #### Key Methods
 
 ##### encode(values)
 Encodes one or more integer IDs into an obfuscated string.
 
 ```ruby
-coder = EncodedId::ReversibleId.new(salt: "my-salt")
+coder = EncodedId::ReversibleId.sqids
 
 # Single ID
 coder.encode(123) # => "p5w9-z27j"
@@ -53,17 +107,22 @@ coder.encode(123) # => "p5w9-z27j"
 coder.encode([78, 45]) # => "z2j7-0dmw"
 ```
 
-##### decode(encoded_id, downcase: true)
+##### decode(encoded_id, downcase: false)
 Decodes an encoded string back to original IDs.
 
 ```ruby
 coder.decode("p5w9-z27j") # => [123]
 coder.decode("z2j7-0dmw") # => [78, 45]
 
-# Handles confused characters
-coder.decode("p5w9-z27J") # => [123]
+# Case-sensitive by default (v1.0.0+)
+coder.decode("p5w9-z27J") # => [] (case doesn't match)
+
+# For case-insensitive matching (pre-v1 behavior)
+coder.decode("p5w9-z27J", downcase: true) # => [123]
 ```
 
+**Note**: As of v1.0.0, decoding is case-sensitive by default (`downcase: false`). Set `downcase: true` for backwards compatibility.
+
 ##### encode_hex(hex_strings) (Experimental)
 Encodes hexadecimal strings (like UUIDs).
 
@@ -73,19 +132,19 @@ coder.encode_hex("9a566b8b-8618-42ab-8db7-a5a0276401fd")
 # => "5jjy-c8d9-hxp2-qsve-rgh9-rxnt-7nb5-tve7-bf84-vr"
 
 # With larger group size for shorter output
-coder = EncodedId::ReversibleId.new(
-  salt: "my-salt", 
-  hex_digit_encoding_group_size: 32
-)
+coder = EncodedId::ReversibleId.sqids(hex_digit_encoding_group_size: 32)
 coder.encode_hex("9a566b8b-8618-42ab-8db7-a5a0276401fd")
 # => "vr7m-qra8-m5y6-dkgj-5rqr-q44e-gp4a-52"
 ```
 
-##### decode_hex(encoded_id, downcase: true) (Experimental)
+##### decode_hex(encoded_id, downcase: false) (Experimental)
 Decodes back to hexadecimal strings.
 
 ```ruby
 coder.decode_hex("w72a-y0az") # => ["10f8c"]
+
+# For case-insensitive decoding (pre-v1 behavior)
+coder.decode_hex("W72A-Y0AZ", downcase: true) # => ["10f8c"]
 ```
 
 ### EncodedId::Alphabet
@@ -116,62 +175,127 @@ alphabet = EncodedId::Alphabet.new(
 
 # Greek alphabet example
 alphabet = EncodedId::Alphabet.new("αβγδεζηθικλμνξοπρστυφχψω")
-coder = EncodedId::ReversibleId.new(salt: "my-salt", alphabet: alphabet)
+coder = EncodedId::ReversibleId.sqids(alphabet: alphabet)
 coder.encode(123) # => "θεαψ-ζκυο"
 ```
 
+### EncodedId::Blocklist
+
+Class for managing profanity/word blocklists.
+
+#### Predefined Blocklists
+
+```ruby
+# Empty blocklist (no filtering)
+EncodedId::Blocklist.empty
+
+# Minimal blocklist (~50 common profane words)
+EncodedId::Blocklist.minimal
+
+# Full Sqids default blocklist (comprehensive)
+EncodedId::Blocklist.sqids_blocklist
+
+# Use in configuration
+coder = EncodedId::ReversibleId.sqids(
+  blocklist: EncodedId::Blocklist.minimal
+)
+```
+
+#### Custom Blocklists
+
+```ruby
+# From array
+blocklist = EncodedId::Blocklist.new(["bad", "offensive", "words"])
+
+# Merge blocklists
+combined = EncodedId::Blocklist.minimal.merge(
+  EncodedId::Blocklist.new(["custom", "words"])
+)
+
+# Filter for specific alphabet (automatic with configuration)
+filtered = blocklist.filter_for_alphabet(EncodedId::Alphabet.modified_crockford)
+```
+
+**Note**: Blocklists are automatically filtered to only include words possible with your configured alphabet. This optimization improves performance.
+
 ## Configuration Options
 
 ### Basic Options
 
-- **salt**: Required secret salt (minimum 4 characters). Changing the salt changes all encoded IDs
-- **length**: Minimum length of encoded string (default: 8)
+- **min_length**: Minimum length of encoded string (default: 8)
 - **max_length**: Maximum allowed length (default: 128) to prevent DoS attacks
 - **max_inputs_per_id**: Maximum IDs encodable together (default: 32)
+- **hex_digit_encoding_group_size**: Group size for hex encoding (default: 4)
 
 ### Encoder Selection
 
 ```ruby
-# Default HashIds encoder
-coder = EncodedId::ReversibleId.new(salt: "my-salt")
+# Sqids encoder (default, no salt required)
+coder = EncodedId::ReversibleId.sqids
 
-# Sqids encoder (requires 'sqids' gem)
-coder = EncodedId::ReversibleId.new(salt: "my-salt", encoder: :sqids)
+# Hashids encoder (requires salt - minimum 4 characters)
+coder = EncodedId::ReversibleId.hashid(salt: "my-salt-minimum-4-chars")
 ```
 
-**Important**: HashIds and Sqids produce different encodings and are not compatible.
+**Important**:
+- As of v1.0.0, `:sqids` is the default encoder
+- **Sqids**: No salt required, automatically avoids blocklisted words via iteration
+- **Hashids**: Salt required (min 4 chars), raises exception if blocklisted word appears
+- HashIds and Sqids produce different encodings and are **not compatible**
+- Do NOT change encoders after going to production with existing encoded IDs
 
-### Formatting Options
+### Blocklist Configuration
+
+#### Blocklist Modes
+
+Control how blocklist checking behaves to balance performance and safety:
 
 ```ruby
-# Custom splitting
-coder = EncodedId::ReversibleId.new(
-  salt: "my-salt",
-  split_at: 3,      # Group every 3 chars
-  split_with: "."   # Use dots
+# :length_threshold (default) - Check blocklist only until encoded length reaches blocklist_max_length
+# Best for most use cases - prevents performance issues with very long IDs
+coder = EncodedId::ReversibleId.sqids(
+  blocklist: EncodedId::Blocklist.minimal,
+  blocklist_mode: :length_threshold,
+  blocklist_max_length: 32  # Stop checking after 32 characters
 )
-coder.encode(123) # => "p5w.9z2.7j"
 
-# No splitting
-coder = EncodedId::ReversibleId.new(
+# :always - Always check blocklist regardless of encoded length
+# Can be slow for long IDs or large blocklists
+coder = EncodedId::ReversibleId.hashid(
   salt: "my-salt",
-  split_at: nil
+  blocklist: ["bad", "words"],
+  blocklist_mode: :always
 )
-coder.encode(123) # => "p5w9z27j"
+
+# :raise_if_likely - Raise error at configuration time if settings likely cause blocklist collisions
+# Prevents configurations that would cause performance issues
+coder = EncodedId::ReversibleId.sqids(
+  min_length: 8,
+  blocklist: ["bad", "words"],
+  blocklist_mode: :raise_if_likely
+)
+# Raises InvalidConfigurationError if min_length > blocklist_max_length
 ```
 
-### Blocklist Configuration
+**Blocklist Behavior by Encoder**:
+- **Sqids**: Iteratively regenerates to avoid blocklisted words (may impact encoding performance)
+- **Hashids**: Raises `EncodedId::BlocklistError` if a blocklisted word appears
+
+**Recommendation**: Use `:length_threshold` mode (default) for best balance of performance and safety.
+
+### Formatting Options
 
 ```ruby
-# Prevent specific words
-coder = EncodedId::ReversibleId.new(
-  salt: "my-salt",
-  blocklist: ["bad", "offensive", "words"]
+# Custom splitting
+coder = EncodedId::ReversibleId.sqids(
+  split_at: 3,      # Group every 3 chars
+  split_with: "."   # Use dots
 )
+coder.encode(123) # => "p5w.9z2.7j"
 
-# Behavior differs by encoder:
-# - HashIds: Raises error if blocklisted word appears
-# - Sqids: Automatically avoids generating blocklisted words
+# No splitting
+coder = EncodedId::ReversibleId.sqids(split_at: nil)
+coder.encode(123) # => "p5w9z27j"
 ```
 
 ## Exception Handling
@@ -183,14 +307,15 @@ coder = EncodedId::ReversibleId.new(
 | `EncodedId::EncodedIdFormatError` | Invalid encoded ID format |
 | `EncodedId::EncodedIdLengthError` | Encoded ID exceeds max_length |
 | `EncodedId::InvalidInputError` | Invalid input (negative integers, too many inputs) |
-| `EncodedId::SaltError` | Invalid salt (too short) |
+| `EncodedId::SaltError` | Invalid salt (too short, only for Hashids) |
+| `EncodedId::BlocklistError` | Generated ID contains blocklisted word (Hashids only) |
 
 ## Usage Examples
 
 ### Basic Usage
 ```ruby
-# Initialize
-coder = EncodedId::ReversibleId.new(salt: "my-secret-salt")
+# Initialize with Sqids (no salt needed)
+coder = EncodedId::ReversibleId.sqids
 
 # Encode/decode cycle
 encoded = coder.encode(123)        # => "p5w9-z27j"
@@ -205,44 +330,79 @@ encoded = coder.encode([78, 45, 92])  # => "z2j7-0dmw-kf8p"
 decoded = coder.decode(encoded)        # => [78, 45, 92]
 ```
 
-### Custom Configuration
+### With Hashids and Blocklist
 ```ruby
-# Highly customized instance
-coder = EncodedId::ReversibleId.new(
+coder = EncodedId::ReversibleId.hashid(
   salt: "my-app-salt",
-  encoder: :sqids,
-  length: 12,
+  min_length: 12,
+  blocklist: EncodedId::Blocklist.minimal,
+  blocklist_mode: :length_threshold
+)
+
+encoded = coder.encode(123)
+# Raises BlocklistError if result contains blocklisted word
+```
+
+### Custom Configuration
+```ruby
+# Highly customized Sqids instance
+coder = EncodedId::ReversibleId.sqids(
+  min_length: 12,
   split_at: 3,
   split_with: ".",
   alphabet: EncodedId::Alphabet.new("0123456789ABCDEF"),
-  blocklist: ["BAD", "FAKE"]
+  blocklist: ["BAD", "FAKE"],
+  blocklist_mode: :length_threshold,
+  blocklist_max_length: 32
 )
 ```
 
 ### Hex Encoding (UUIDs)
 ```ruby
 # For encoding UUIDs efficiently
-coder = EncodedId::ReversibleId.new(
-  salt: "my-salt",
-  hex_digit_encoding_group_size: 32
-)
+coder = EncodedId::ReversibleId.sqids(hex_digit_encoding_group_size: 32)
 
 uuid = "550e8400-e29b-41d4-a716-446655440000"
 encoded = coder.encode_hex(uuid)
-decoded = coder.decode_hex(encoded).first # => original UUID
+decoded = coder.decode_hex(encoded).first # => original UUID (without hyphens)
 ```
 
 ## Performance Considerations
 
-1. **Algorithm Choice**: 
+1. **Algorithm Choice**:
    - HashIds: Faster encoding, especially with blocklists
-   - Sqids: Faster decoding
+   - Sqids: Faster decoding, automatically avoids blocklisted words
+
+2. **Blocklist Impact**:
+   - Large blocklists slow encoding, especially with Sqids (which iterates to avoid words)
+   - Hashids may raise exceptions requiring retry logic
+   - Use `blocklist_mode: :length_threshold` for best performance
+   - `:always` mode can significantly impact encoding speed for long IDs
+   - Blocklists are automatically filtered for your alphabet, improving performance
+
+3. **Blocklist Mode Performance**:
+   - `:length_threshold` (default): Only checks blocklist for IDs ≤ `blocklist_max_length` (default: 32)
+   - `:always`: Checks all IDs regardless of length (can be slow)
+   - `:raise_if_likely`: Validates configuration at initialization to prevent performance issues
+
+4. **Length vs Performance**: Longer minimum lengths may require more computation
+
+5. **Memory Usage**: The gem uses optimized implementations to minimize memory allocation
 
-2. **Blocklist Impact**: Large blocklists can slow down encoding, especially with Sqids
+## Version Compatibility
 
-3. **Length vs Performance**: Longer minimum lengths may require more computation
+**v1.0.0 Breaking Changes:**
 
-4. **Memory Usage**: The gem uses optimized implementations to minimize memory allocation
+1. **Default encoder**: Changed from `:hashids` to `:sqids`
+2. **Case sensitivity**: `decode` is now case-sensitive by default (`downcase: false`)
+   - Pre-v1: `decode("ABC")` and `decode("abc")` were equivalent
+   - v1.0.0+: These produce different results unless `downcase: true`
+3. **Salt requirement**: Sqids (default) doesn't require salt; Hashids still requires salt
+4. **Migration**: For backwards compatibility with pre-v1:
+   ```ruby
+   coder = EncodedId::ReversibleId.hashid(salt: "your-salt")
+   decoded = coder.decode(id, downcase: true)
+   ```
 
 ## Security Notes
 
@@ -252,32 +412,26 @@ Use encoded IDs for:
 - Hiding sequential database IDs
 - Creating user-friendly URLs
 - Preventing ID enumeration attacks
+- Obscuring business metrics (user counts, order volumes)
 
 Do NOT use for:
 - Secure tokens
 - Authentication
 - Sensitive data protection
+- Cryptographic purposes
 
 ## Installation
 
 ```ruby
 # Gemfile
 gem 'encoded_id'
-
-# Or install directly
-gem install encoded_id
-```
-
-For Sqids support:
-```ruby
-gem 'encoded_id'
-gem 'sqids'
 ```
 
 ## Best Practices
 
-1. **Salt Management**: Use a strong, unique salt and store it securely (e.g., environment variables)
-2. **Consistent Configuration**: Once in production, don't change salt or encoder
-3. **Error Handling**: Always handle potential exceptions when decoding user input
-4. **Length Limits**: Set appropriate max_length to prevent DoS attacks
-5. **Validation**: Validate decoded IDs before using them in database queries
+1. **Consistent Configuration**: Once in production, don't change salt, encoder, or alphabet
+2. **Error Handling**: Always handle potential exceptions when decoding user input
+3. **Length Limits**: Set appropriate max_length to prevent DoS attacks
+4. **Validation**: Validate decoded IDs before using them in database queries
+5. **Blocklist Mode**: Use `:length_threshold` (default) for production - best performance/safety balance
+6. **Factory Methods**: Prefer `ReversibleId.sqids()` and `ReversibleId.hashid()` over constructor

data/lib/encoded_id/alphabet.rb

@@ -3,6 +3,7 @@
 # rbs_inline: enabled
 
 module EncodedId
+  # Represents a character set (alphabet) used for encoding IDs, with optional character equivalences.
   class Alphabet
     MIN_UNIQUE_CHARACTERS = 16
 
@@ -94,6 +95,7 @@ module EncodedId
       unique_characters.size >= MIN_UNIQUE_CHARACTERS
     end
 
+    # Validates equivalences ensure: keys map to values in the alphabet, and keys are not already in the alphabet
     # @rbs (Hash[String, String]? equivalences) -> bool
     def valid_equivalences?(equivalences)
       return true if equivalences.nil?