sqinky 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 40416492e70faec554b8a67ff4c00c8d0ee9e4a0b2b76a885adffa0dbce64294
+  data.tar.gz: 1d538c90645378e38d3007b0d3473f07b264433cf95eabb826c392cc4099ef05
+SHA512:
+  metadata.gz: c55b2e64caf756a43f6336fe99135d5eeb4e7a10e664c87bbfb17143ab91ab1e75b8b2a1350061588172678997167da6219ae5c0e87ae1b5faf87679735f30c7
+  data.tar.gz: 7f83412fe303c907f842b1c510675b2d9efc00e2721fa3a2d85b9ac679d6d0488c30a95c52b42b1fb4f0a9882e7f170ae2320ae217596e39b64d9884e5ec6c94

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+### Unreleased
+
+### 0.1.0
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"sqinky" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["david.uhlig@gmail.com"](mailto:"david.uhlig@gmail.com").

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 David Uhlig
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,228 @@
+[Sqids]: https://sqids.org/
+
+# 🫟 Sqinky
+
+## 🦑 [Sqids] for your Active Record models.
+
+[![License](https://img.shields.io/github/license/david-uhlig/sqinky?label=License&labelColor=343B42&color=blue)](https://github.com/david-uhlig/sqinky/blob/main/LICENSE.md) [![Gem Version](https://badge.fury.io/rb/sqinky.svg)](https://badge.fury.io/rb/sqinky) [![Tests](https://github.com/david-uhlig/sqinky/actions/workflows/main.yml/badge.svg)](https://github.com/david-uhlig/sqinky/actions/workflows/main.yml)
+
+> **What is Sqids?**
+> 
+> Sqids (pronounced "squids") is an open-source library that lets you generate short unique identifiers from numbers. These IDs are URL-safe, can encode several numbers, and do not contain common profanity words.
+> 
+> This is what they look like: `https://example.com/CN4Xst`
+> 
+> Source: https://sqids.org/
+
+Sqinky brings Sqids-based identifier encoding[^1] and decoding directly to your Active Record models. 
+
+The library adds a thin access layer on top of [Sqids](https://sqids.org/) to work effortlessly with short, unique, and URL-safe identifiers. It supports encodings composed of multiple attributes and multiple encodings per model. Sqinky does not store encodings in the database. Instead, it decodes them on the fly back to the initial arguments and uses standard Active Record methods to retrieve the records.
+
+#### Key features
+- **Dynamic Encodings**: Computed from record attributes on the fly. No extra data is stored in the database.
+- **Auto-generated Helpers**: Provides `find_by_*`, `find_by_*!`, `destroy_by_*`, and `delete_by_*` methods.
+- **Multiple Attributes**: Encode and decode composite identifiers (e.g., `[account_id, id]`).
+- **Customizable**: Pass any Sqids option (`alphabet`, `min_length`, and `blocklist`) per encoder.
+
+## Installation
+
+Run the following command to add Sqinky to your Gemfile:
+
+```bash
+bundle add sqinky
+```
+
+## Usage
+
+To use it include `Sqinky::IdentifierEncoding` in your Active Record model and 
+* add the `encodes_identifier` macro for a single attribute (defaults to `:id`), or  
+* add the `encodes_identifiers` macro for multiple attributes.
+* See [Parameter Overview](#parameter-overview) for all configuration options.
+
+This generates the encoding methods `<attribute>_encoding` and `<attribute>_encoding!` (by default; configurable), and the dynamic Active Record methods `find_by_*`, `find_by_*!`, `delete_by_*`, and `destroy_by_*`. See [Generated Method Overview](#generated-methods-overview) for a detailed overview.
+
+#### Basic usage
+```ruby
+class Comment < ApplicationRecord
+  include Sqinky::IdentifierEncoding
+  
+  encodes_identifier :id
+end
+
+# Retrieving the encoding
+comment = Comment.create!(text: "Sqinky is the linky that breaks when you drinky.")
+comment.id # => 1
+comment.id_encoding # => "Uk"
+
+# Finding the comment back
+Comment.find_by_id_encoding("Uk") # => #<Comment id: 1, ...>
+Comment.find_by_id_encoding!("Uk") # Raises ActiveRecord::RecordNotFound if not found
+Comment.destroy_by_id_encoding("Uk")
+Comment.delete_by_id_encoding("Uk")
+```
+
+> [!WARNING]
+> For consistent behavior only use attributes with `Integer` values `>= 0`.
+
+> [!NOTE]
+> `id_encoding` in all these methods is dynamically generated from the `id` attribute. 
+> * If you encode a different attribute, e.g. `user_id` the method names change to  `user_id_encoding`. 
+> * Composite encodings are connected with `_and_` in the specified order: `id_and_user_id_encoding`. 
+> * You can choose your own name with the `as:` parameter: `as: :token # => instance.token`.
+
+#### Most common workflow
+1. Receive encoding from a **persisted** record: `user.id_encoding # => "Uk"`.
+2. Pass the encoding around, either via URL `/users/Uk/show` or store it in a session.
+3. Retrieve the record through the encoding `User.find_by_id_encoding("Uk") # => #<User id: 1, ...>`
+
+### Multiple Attributes & Custom Names
+
+Sqinky can compose multiple attributes into a single encoding, here: `:id` and `:account_id`. Normally, this would dynamically generate `id_and_account_id_encoding` methods, but here we rename them to `token` with the `as:` parameter.
+
+```ruby
+class Invitation < ApplicationRecord
+  include Sqinky::IdentifierEncoding
+
+  # Encode both `id` and `account_id` into a single `token`
+  encodes_identifiers :id, :account_id, as: :token
+end
+
+invitation = Invitation.create!(account_id: 42)
+invitation.token # => "ySrS"
+
+# Internally calls find_by(id: 1, account_id: 42)
+Invitation.find_by_token("ySrS")
+```
+
+> [!NOTE]
+> Mind the pluralized `encodes_identifiers` when encoding multiple attributes.
+
+### Decoding Helper
+
+If you need to access the decoded hash, you can pass your preferred method name to the `decodes_as:` parameter, e.g. `decodes_as: :id_decoding`. This will generate a dynamic class method, that takes a single argument: the encoding. 
+
+```ruby
+class Order < ApplicationRecord
+  include Sqinky::IdentifierEncoding
+
+  encodes_identifier :id, as: :public_id, decodes_as: :decode_public_id
+end
+
+Order.decode_public_id("86Rf07") # => { id: 1 }
+```
+
+### Custom Sqids Options
+
+Configure Sqids by passing in the [Sqids options](https://github.com/sqids/sqids-ruby?tab=readme-ov-file#%E2%80%8D-examples): `alphabet`, `min_length`, and `blocklist`. Each coder can have its own configuration.
+
+```ruby
+class Comment < ApplicationRecord
+  include Sqinky::IdentifierEncoding
+
+  encodes_identifier :id, alphabet: "abcdef0123456789", min_length: 10
+end
+```
+
+### Multiple Encodings
+
+A model can have multiple encodings, even for the same attribute, as long as they have distinct `as:` method names.
+
+```ruby
+class Post < ApplicationRecord
+  include Sqinky::IdentifierEncoding
+  
+  encodes_identifier
+  encodes_identifiers :id, :tenant_id
+end
+
+post = Post.create!(title: "How Sqinky became so inkie.")
+post.id # => 212
+post.tenant_id # => 42
+post.id_encoding # => "37E"
+post.id_and_tenant_id_encoding # "jGTwn"
+
+Post.find_by_id_encoding("37E") # => #<Post id: 212, ...>
+Post.find_by_id_and_tenant_id_encoding("jGTwn") # => #<Post id: 212, ...>
+```
+
+### Inheritance
+
+Since Sqinky generates regular methods, it can be included anywhere in the class tree. Child classes can use the parents' methods or overwrite them with their own. It isn't required for the including class to have the configured attributes.
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  include Sqinky::IdentifierEncoding
+  
+  encodes_identifier
+end
+
+class Label < ApplicationRecord
+end
+
+label = Label.create!(text: "Pinky")
+label.id = 1
+label.id_encoding # => "Uk"
+```
+
+### Parameter Overview
+
+#### `encodes_identifier`
+
+| Parameter         | Default | Description                                                                                 |
+|-------------------|---------|---------------------------------------------------------------------------------------------|
+| `attribute`       | `:id`   | The attribute to encode. Should only have `Integer` `>= 0` values.                          |
+| `as:`             | `nil`   | If `nil` inferred as `<attribute>_encoding`.                                                |
+| `decodes_as:`     | `nil`   | Name of the decoding class method. If `nil` no such method is generated.                    |
+| `**sqids_options` | `{}`    | Sqids options passed through to `Sqids.new`, e.g. `min_length`, `alphabet`, and `blocklist` |
+
+#### `encodes_identifiers`
+
+| Parameter         | Default | Description                                                                                 |
+|-------------------|---------|---------------------------------------------------------------------------------------------|
+| `*attributes`     |         | The attribute(s) to encode. Should only have `Integer` `>= 0` values.                       |
+| `as:`             | `nil`   | If `nil` inferred as `<attribute[_and_<attribute>]>_encoding`.                              |
+| `decodes_as:`     | `nil`   | Name of the decoding class method. If `nil` no such method is generated.                    |
+| `**sqids_options` | `{}`    | Sqids options passed through to `Sqids.new`, e.g. `min_length`, `alphabet`, and `blocklist` |
+
+### Generated Methods Overview
+
+| Method                            | Description                                                                                        |
+|-----------------------------------|----------------------------------------------------------------------------------------------------|
+| `instance.<as>`                   | Returns the Sqids encoding for the configured attributes. Returns `nil` if any attribute is `nil`. |
+| `instance.<as>!`                  | Same as above, but raises `ArgumentError` if any attribute is not an `Integer`.                    |
+| `Class.<decodes_as>(encoding)`    | Returns the decoded hash, e.g. `{ id: 42 }`.                                                       |
+| `Class.find_by_<as>(encoding)`    | Decodes `encoding` and passes the decoded hash to `find_by(...)`                                   |
+| `Class.find_by_<as>(encoding)!`   | Decodes `encoding` and passes the decoded hash to `find_by(...)!`                                  |
+| `Class.destroy_by_<as>(encoding)` | Decodes `encoding` and passes the decoded hash to `destroy_by(...)`                                |
+| `Class.delete_by_<as>(encoding)`  | Decodes `encoding` and passes the decoded hash to `delete_by(...)`                                 |
+
+## Development
+
+### Setup
+
+After checking out the repo, run the setup script to install dependencies:
+
+```bash
+bin/setup
+```
+
+This project uses [mise](https://mise.jdx.dev/) for managing Ruby versions and tasks. If you have mise installed, you can use it to run common tasks.
+
+### Scripts & Tasks
+
+- `bin/console`: Open an interactive prompt to experiment with the code.
+- `rake spec`: Run the test suite.
+- `rake standard`: Run the StandardRB linter.
+- `bundle exec appraisal install`: 
+- `bundle exec appraisal rake spec`: Run tests against all supported Rails versions.
+- `mise run ci`: Run the local CI pipeline (linting and multi-Rails tests).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/david-uhlig/sqinky. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/david-uhlig/sqinky/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.md).
+
+[^1]: In the context of this library the term `encoding` refers to the output of `Sqids.new.encode([<number>])`. In Sqids terminology this is a *short unique identifier from numbers*.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/lib/sqinky/identifier_encoding.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "sqids"
+
+module Sqinky
+  # Add Sqids-based identifier encoding/decoding helpers to Active Record models.
+  #
+  # {Sqids}[https://sqids.org/] is an open-source library that lets you generate short unique identifiers from numbers.
+  # These IDs are URL-safe, can encode several numbers, and do not contain common profanity words.
+  #
+  # *Note*: Sqids encodings are computed dynamically from record attributes and do not need to be stored.
+  #
+  # Sqinky adds a thin access layer on top of Sqids to work effortlessly with Sqids in Active Record models.
+  # It generates an encoding method, e.g. +id_encoding+ and database methods for finding and deleting matching records,
+  # e.g. +find_by_id_encoding+, +find_by_id_encoding!+, +destroy_by_id_encoding+, and +delete_by_id_encoding+.  Sqinky
+  # does not persist the encoding to the database. It supports encodings composed of multiple attributes, and multiple
+  # encodings per model.
+  module IdentifierEncoding
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Generates methods for creating and consuming a single identifier attribute encoding, typically for the primary
+      # key +id+.
+      #
+      # #### Note
+      # * If the +as+ argument is missing, it is generated as +<attribute>_encoding+.
+      # * The referenced +attribute+ must be present when the generated +#{as}+ method is called.
+      #
+      # #### Generates
+      # * +#<as>+ - Generates the Sqids encoding from the attribute value.
+      # * +#<as>!+ - Generates the Sqids encoding from the attribute value. Raises +ArgumentError+ the attribute value is noninteger.
+      # * +#<decodes_as>(encoding)+ - Decodes a Sqids encoding back to the attribute-value hash. (Optional)
+      # * +.find_by_<as>(encoding)+ - Finds record by +encoding+ or returns nil.
+      # * +.find_by_<as>!(encoding)+ - Finds record by +encoding+ or raises +ActiveRecord::RecordNotFound+ error.
+      # * +.destroy_by_<as>(encoding)+ - Destroys record by +encoding+.
+      # * +.delete_by_<as>(encoding)+ - Deletes record by +encoding+.
+      #
+      # @param attribute [Symbol] Attribute to encode. Must take positive +Integer+ values.
+      # @param as [Symbol, nil] Optional name of the instance method that returns the encoding. Also part of the database methods, e.g. +find_by_<as>+. If missing, it is generated from the attribute name, e.g. +id_encoding+.
+      # @param decodes_as [Symbol, nil] Optional class method name that, when given an encoding, returns a hash of decoded attribute values. If missing, no such method is generated.
+      # @param sqids_options [Hash] Options forwarded to +Sqids.new+, e.g. +alphabet+, +min_length+, and +blocklist+.
+      #
+      # @return [Void]
+      #
+      # @see .encodes_identifiers
+      def encodes_identifier(attribute = :id, as: nil, decodes_as: nil, **sqids_options)
+        encodes_identifiers(attribute, as: as, decodes_as: decodes_as, **sqids_options)
+      end
+
+      # Generates methods for creating and consuming a single or multiple identifier attribute encoding.
+      #
+      # #### Note
+      # * If the +as+ argument is missing, it is generated as +<attribute>_encoding+. If multiple attributes are present they are joined by +_and_+, e.g. +<attribute>_and_<attribute>_encoding+.
+      # * The referenced +attribute+ must be present when the generated +#{as}+ method is called.
+      #
+      # #### Generates
+      # * +#<as>+ - Generates the Sqids encoding from the attribute values.
+      # * +#<as>!+ - Generates the Sqids encoding from the attribute values. Raises +ArgumentError+ if any attribute value is noninteger.
+      # * +#<decodes_as>(encoding)+ - Decodes a Sqids encoding back to the attributes-values hash. (Optional)
+      # * +.find_by_<as>(encoding)+ - Finds record by +encoding+ or returns nil.
+      # * +.find_by_<as>!(encoding)+ - Finds record by +encoding+ or raises +ActiveRecord::RecordNotFound+ error.
+      # * +.destroy_by_<as>(encoding)+ - Destroys record by +encoding+.
+      # * +.delete_by_<as>(encoding)+ - Deletes record by +encoding+.
+      #
+      # ### Usage
+      #
+      # @example Basic usage for an `id` primary key
+      #   class Post < ApplicationRecord
+      #     include Sqinky::IdentifierEncoding
+      #
+      #     # Encodes the `id` attribute into `id_encoding`
+      #     encodes_identifier
+      #   end
+      #
+      #   post = Post.create!(title: "Hello")
+      #   post.id           # => 1
+      #   post.id_encoding  # => "Uk"
+      #   Post.find_by_id_encoding("Uk")   # => #<Post id: 1, ...>
+      #   Post.find_by_id_encoding!("Uk")  # => Same as above, raises if not found.
+      #   Post.destroy_by_id_encoding("Uk")
+      #   Post.delete_by_id_encoding("Uk")
+      #
+      # @example Encoding multiple attributes
+      #   class Invitation < ApplicationRecord
+      #     include Sqinky::IdentifierEncoding
+      #
+      #     # Encode `account_id` and `id`
+      #     encodes_identifiers :id, :account_id
+      #   end
+      #
+      #   invitation = Invitation.create!(account_id: 42)
+      #   invitation.id                         # => 1
+      #   invitation.id_and_account_id_encoding # => "ySrS"
+      #   Invitation.find_by_id_and_account_id_encoding("ySrS")
+      #   # => Internally calls find_by(id: 1, account_id: 42)
+      #   # => #<Invitation id: 1, account_id: 42, ...>
+      #   Invitation.find_by_id_and_account_id_encoding!("ySrS")
+      #   Invitation.destroy_by_id_and_account_id_encoding("ySrS")
+      #   Invitation.delete_by_id_and_account_id_encoding("ySrS")
+      #
+      # @example Renaming the helper methods
+      #   class Invitation < ApplicationRecord
+      #     include Sqinky::IdentifierEncoding
+      #
+      #     # Encode `account_id` and `id` into `token`
+      #     encodes_identifiers :id, :account_id, as: :token
+      #   end
+      #
+      #   invitation = Invitation.create!(account_id: 42)
+      #   invitation.id                        # => 1
+      #   invitation.token                     # => "ySrS"
+      #   Invitation.find_by_token("ySrS")
+      #   # => Internally calls find_by(id: 1, account_id: 42)
+      #   # => #<Invitation id: 1, account_id: 42, ...>
+      #   Invitation.find_by_token!("ySrS")
+      #   Invitation.destroy_by_token("ySrS")
+      #   Invitation.delete_by_token("ySrS")
+      #
+      # @example Generating a decoding helper
+      #   class Order < ApplicationRecord
+      #     include Sqinky::IdentifierEncoding
+      #
+      #     # Add a decoding helper that returns the decoded attributes hash
+      #     encodes_identifiers :shop_id, :id,
+      #                         as: :public_id,
+      #                         decodes_as: :decode_public_id
+      #   end
+      #
+      #   order = Order.create!(shop_id: 10)
+      #   encoded = order.public_id           # => e.g. "86Rf07"
+      #   Order.decode_public_id(encoded)
+      #   # => { shop_id: 10, id: 1 }
+      #
+      # @example Passing Sqids options through
+      #   class Comment < ApplicationRecord
+      #     include Sqinky::IdentifierEncoding
+      #
+      #     # Use a custom alphabet and minimum length for generated IDs
+      #     encodes_identifier :id,
+      #                        alphabet: "abc",
+      #                        min_length: 10
+      #   end
+      #
+      #   comment = Comment.create!
+      #   comment.id_encoding        # => Always at least 10 characters, consists only of "abc" characters.
+      #
+      # @example Multiple encoders in a single model
+      #   class Membership < ApplicationRecord
+      #     include Sqinky::IdentifierEncoding
+      #
+      #     # Encodes +id+ into +id_encoding+.
+      #     encode_identifier
+      #     # Encodes +id+ (again) into +code+ with the +abc+ alphabet.
+      #     encode_identifier as: :code, alphabet: "abc"
+      #     # Encodes both +user_id+ and +group_id+ into a single token. Make sure to
+      #     # use a different +as+ (and +decodes_as+) value for each encoder, otherwise they will overwrite
+      #     # each other.
+      #     encodes_identifiers :user_id, :group_id, as: :membership_token
+      #   end
+      #
+      #   membership = Membership.create!(user_id: 44, group_id: 12)
+      #   token = membership.id_encoding
+      #   # => "Uk"
+      #   Membership.find_by_id_encoding(token)
+      #   # => Internally calls `find_by(id: 1)`
+      #
+      #   code = membership.code
+      #   # => "aa"
+      #   Membership.find_by_code(code)
+      #   # => Internally calls `find_by(id: 1)`
+      #
+      #   membership_token = membership.membership_token
+      #   # => "7edZ"
+      #   Membership.find_by_membership_token(membership_token)
+      #   # => Internally calls `find_by(user_id: 44, group_id: 12)
+      #
+      # @return [Void]
+      #
+      # @param attributes [Array<Symbol>] List of attributes to encode. At least one attribute must be provided.
+      # @param as [Symbol, nil] Name of the instance method that returns the encoding. Also part of the database methods, e.g. +find_by_<as>+. If missing, it is generated from the attribute names, e.g. +id_encoding+ or +id_and_tenant_id_encoding+.
+      # @param decodes_as [Symbol, nil] Optional class method name that, when given an encoding, returns a hash of decoded attribute values. If missing, no such method is generated.
+      # @param sqids_options [Hash] Options forwarded to +Sqids.new+, e.g. +alphabet+, +min_length+, and +blocklist+.
+      #
+      # @raise [ArgumentError] if no attributes are given.
+      #
+      # @return [void]
+      def encodes_identifiers(*attributes, as: nil, decodes_as: nil, **sqids_options)
+        if attributes.compact_blank!.empty?
+          raise ArgumentError, <<~MSG
+            Must specify at least one attribute. Hint: Use `encodes_identifier` instead to encode the primary key 
+            without having to specify the `:id` attribute.
+          MSG
+        end
+        coder = Sqids.new(**sqids_options)
+        encoding_method_name = as.presence || attributes.join("_and_").concat("_encoding")
+        database_methods = %w[find_by find_by! destroy_by delete_by].map do |base_method|
+          # ["find_by!", "find_by_id_encoding!"]
+          [base_method, base_method.gsub(/(\w+?)(!?)\b/, "\\1_#{encoding_method_name}\\2")]
+        end
+
+        # @!method <encoding_method_name>
+        #   Returns the Sqids-encoded identifier for the configured attributes.
+        #
+        #   Will return an irreversible encoding if any attribute is noninteger. Use the bang method to ensure a
+        #   reversible encoding.
+        #
+        #   @raises [ArgumentError] If any of the attributes is a number below 0 or above +Sqids.max_value+.
+        #   @return [String, nil] Encoded identifier or nil if any of the attributes is +blank?+.
+        define_method(encoding_method_name) do
+          values = attributes.map { send(_1) }
+          values.any?(&:blank?) ? nil : coder.encode(values)
+        end
+
+        # @!method <encoding_method_name>
+        #   Returns the Sqids-encoded identifier for the configured attributes.
+        #
+        #   Ensures a reversible encoding.
+        #
+        #   @raises [ArgumentError] If any of the attributes is not a positive integer between 0 and +Sqids.max_value+
+        #   @return [String] Encoded identifier.
+        define_method("#{encoding_method_name}!") do
+          values = attributes.map { send(_1) }
+          unless values.all? { _1.is_a?(Integer) }
+            raise ArgumentError, <<~MSG
+              Encoding supports integers between 0 and #{Sqids.max_value}.
+
+              Received: #{attributes.zip(values).to_h}
+            MSG
+          end
+          coder.encode(values)
+        end
+
+        database_methods.each do |base_method, dynamic_method|
+          # @!method find_by_<dynamic_method>(encoding)
+          #   Find a record by decoding the given encoding into the configured
+          #   attributes, then delegating to the corresponding Active Record
+          #   query method (e.g. `find_by`, `find_by!`, `destroy_by`, `delete_by`).
+          #
+          #   @param encoding [String] Sqids-encoded identifier
+          #   @return [Object, nil] model instance or result of the delegated
+          #     query method
+          #
+          # The actual method names are generated dynamically, e.g.:
+          # `find_by_id_encoding`, `find_by_id_encoding!`,
+          # `destroy_by_id_encoding`, `delete_by_id_encoding`.
+          define_singleton_method(dynamic_method) do |encoding|
+            values = coder.decode(encoding)
+            args = attributes.zip(values).to_h
+            send(base_method, args)
+          end
+        end
+
+        unless decodes_as.blank?
+          decoding_method_name = decodes_as.to_s
+          # @!method <decodes_as>(encoding)
+          #   Decode the given encoding into a hash mapping each configured
+          #   attribute to its decoded numeric value.
+          #
+          #   @param encoding [String] Sqids-encoded identifier
+          #   @return [Hash{Symbol=>Integer}] decoded attribute values
+          define_singleton_method(decoding_method_name) do |encoding|
+            values = coder.decode(encoding)
+            attributes.zip(values).to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sqinky/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Sqinky
+  VERSION = "0.1.0"
+end

data/lib/sqinky.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "sqinky/version"
+require_relative "sqinky/identifier_encoding"
+
+module Sqinky
+end

metadata

@@ -0,0 +1,212 @@
+--- !ruby/object:Gem::Specification
+name: sqinky
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David Uhlig
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-03-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: sqids
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 'Sqinky adds a thin access layer on top of Sqids to work effortlessly
+  with Sqids in Active Record models. It supports encodings composed of multiple attributes,
+  and multiple encodings per model.
+
+  '
+email:
+- david.uhlig@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.md
+- README.md
+- Rakefile
+- lib/sqinky.rb
+- lib/sqinky/identifier_encoding.rb
+- lib/sqinky/version.rb
+homepage: https://github.com/david-uhlig/sqinky
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/david-uhlig/sqinky
+  source_code_uri: https://github.com/david-uhlig/sqinky
+  changelog_uri: https://github.com/david-uhlig/sqinky/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Add Sqids-based identifier encoding/decoding helpers to Active Record models.
+test_files: []