🫟 Sqinky

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¹ and decoding directly to your Active Record models.

The library adds a thin access layer on top of Sqids 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.

• 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.

Run the following command to add Sqinky to your Gemfile:

bundle add sqinky

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 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 for a detailed overview.

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")

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, ...>

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.

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")

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.

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 }

Configure Sqids by passing in the Sqids options: alphabet, min_length, and blocklist. Each coder can have its own configuration.

class Comment < ApplicationRecord
  include Sqinky::IdentifierEncoding

  encodes_identifier :id, alphabet: "abcdef0123456789", min_length: 10
end

A model can have multiple encodings, even for the same attribute, as long as they have distinct as: method names.

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, ...>

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.

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"

Sqinky generates these methods when invoking encodes_identifier(s):

After checking out the repo, run the setup script to install dependencies:

bin/setup

This project uses mise for managing Ruby versions and tasks. If you have mise installed, you can use it to run common 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).

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.

The gem is available as open source under the terms of the MIT License.