slugifiable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d06633ba0907f8ee400648856e3d8dbc95fc647be40d60780ae01ebbb6eeb7d3
+  data.tar.gz: d40cae2d3fc081af04bd6fac08ea8640d8174c1e59b07652c92bab72eb8a18ca
+SHA512:
+  metadata.gz: 39dfad3e03b4cfef9946a929c5fe21585f2aab1ef1922d2f13ad8d10d6d4b732e3eaf6d4dcff545d9664d0395909fa6fa5e40a92801627625ef4034467b93bd9
+  data.tar.gz: 8b726b22d56141b633f415460f8a8f8e7042379bc06aebb383f15360914b294bf29a0fffe2aa5e97e25577dab3e962d2b221bf7f18ab0d8822437f77ca97bfef

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+## [0.1.0] - 2024-10-30
+
+- Initial release
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Javi R
+
+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,178 @@
+# 🐌 `slugifiable` - Rails gem to generate SEO-friendly slugs
+
+[![Gem Version](https://badge.fury.io/rb/slugifiable.svg)](https://badge.fury.io/rb/slugifiable)
+
+Automatically generates unique slugs for your Rails' model records, so you can expose SEO-friendly URLs.
+
+Example:
+```
+https://myapp.com/products/big-red-backpack-321678
+```
+
+Where `big-red-backpack-321678` is the slug.
+
+`slugifiable` can generate:
+- Slugs like `"big-red-backpack"` or `"big-red-backpack-321678"`: unique, string-based slugs based on any attribute, such as `product.name`
+- Slugs like `"d4735e3a265"`: unique **hex string slugs**
+- Slugs like `321678`: unique **number-only slugs**
+
+## Why
+
+When building Rails apps, we usually need to expose _something_ in the URL to identify a record, like:
+```
+https://myapp.com/products/123
+```
+
+But exposing IDs (like `123`) is not usually good practice. It's not SEO-friendly, it can give away how many records you have in the database, it could also be an attack vector, and it just feels off.
+
+It would be much better to have a random-like string or number instead, while still remaining unique and identifiable:
+```
+https://myapp.com/products/d4735e3a265
+```
+
+Or better yet, use other instance attribute (like `product.name`) to build the slug:
+```
+https://myapp.com/products/big-red-backpack
+```
+
+`slugifiable` takes care of building all these kinds of slugs for you.
+
+## Installation
+
+Add this line to your application's Gemfile:
+```ruby
+gem 'slugifiable'
+```
+
+Then run `bundle install`.
+
+After installing the gem, add `include Slugifiable::Model` to any ActiveRecord model, like this:
+```ruby
+class Product < ApplicationRecord
+  include Slugifiable::Model # Adding this provides all the required slug-related methods to your model
+end
+```
+
+That's it!
+
+Then you can, for example, get the slug for a product like this:
+```ruby
+Product.first.slug
+=> "4e07408562b"
+```
+
+You can also define how to generate slugs:
+```ruby
+class Product < ApplicationRecord
+  include Slugifiable::Model
+  generate_slug_based_on :name
+end
+```
+
+And this will generate slugs based on your `Product` instance `name`, like:
+```ruby
+Product.first.slug
+=> "big-red-backpack"
+```
+
+If your model has a `slug` attribute in the database, `slugifiable` will automatically generate a slug for that model upon instance creation, and save it to the DB.
+
+If you're generating slugs based off the model `id`, you can also set a desired length:
+```ruby
+class Product < ApplicationRecord
+  include Slugifiable::Model
+  generate_slug_based_on :id, length: 6
+end
+```
+
+Which would return something like:
+```ruby
+Product.first.slug
+=> "6b86b2"
+```
+
+More details in the "How to use" section.
+
+## How to use
+
+Slugs should never change, so it's recommended you save your slugs to the database.
+
+Therefore, all models that include `Slugifiable::Model` should have a `slug` attribute that persists the slug in the database. If your model doesn't have a `slug` attribute yet, just run:
+```
+rails g migration addSlugTo<MODEL_NAME> slug:text
+```
+
+where `<MODEL_NAME>` is your model name in plural, and then run:
+```
+rails db:migrate
+```
+
+And your model should now have a `slug` attribute in the database.
+
+When a model has a `slug` attribute, `slugifiable` automatically generates a slug for that model upon instance creation, and saves it to the DB.
+
+`slugifiable` can also work without persisting slugs to the databse, though: you can always run `.slug`, and that will give you a valid, unique slug for your record.
+
+### Define how slugs are generated
+
+By default, when you include `Slugifiable::Model`, slugs will be generated as a random-looking string based off the record `id` (SHA hash)
+
+`slugifiable` supports both `id` and `uuid`.
+
+The default setting is:
+```ruby
+generate_slug_based_on id: :hex_string
+```
+
+Which returns slugs like: `d4735e3a265`
+
+If you don't like hex strings, you can get number-only slugs with:
+```ruby
+generate_slug_based_on id: :number
+```
+
+Which will return slugs like: `321678` – nonconsecutive, nonincremental, not a total count.
+
+When you're generating obfuscated slugs (based on `id`), you can specify a desired slug length:
+```ruby
+generate_slug_based_on id: :number, length: 3
+```
+
+The length should be a positive number between 1 and 64.
+
+If instead of obfuscated slugs you want human-readable slugs, you can specify an attribute to base your slugs off of. For example:
+```ruby
+generate_slug_based_on :name
+```
+
+Will look for a `name` attribute in your instance, and use its value to generate the slug. So if you have a product like:
+```ruby
+Product.first.name
+=> "Big Red Backpack"
+```
+
+then the slug will be computed as:
+```ruby
+Product.first.slug
+=> "big-red-backpack"
+```
+
+There may be collisions if two records share the same name – but slugs should be unique! To resolve this, when this happens, `slugifiable` will append a unique string at the end to make the slug unique:
+```ruby
+Product.first.slug
+=> "big-red-backpack-321678"
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/slugifiable. Our code of conduct is: just be nice and make your mom proud of what you do and post online.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/lib/slugifiable/model.rb

@@ -0,0 +1,159 @@
+module Slugifiable
+  module Model
+    extend ActiveSupport::Concern
+
+    # This concern makes objects have a string slug based on their ID or another specified attribute
+    #
+    # To use, include this in any ActiveRecord model:
+    # ```
+    # include Slugifiable::Model
+    # ```
+    #
+    # By default all slugs will be a string computed from the record ID:
+    # ```
+    # generate_slug_based_on :id
+    # ```
+    #
+    # but optionally, you can also specify to compute the slug as a number:
+    # ```
+    # generate_slug_based_on id: :number
+    # ```
+    #
+    # or compute the slug based off any other attribute:
+    # ```
+    # generate_slug_based_on :name
+    # ```
+
+    DEFAULT_SLUG_GENERATION_STRATEGY = :compute_slug_as_string
+    DEFAULT_SLUG_STRING_LENGTH = 11
+    DEFAULT_SLUG_NUMBER_LENGTH = 6
+
+    included do
+      after_create :set_slug
+      after_find :update_slug_if_nil
+      validates :slug, uniqueness: true
+    end
+
+    class_methods do
+      def generate_slug_based_on(strategy, options = {})
+        define_method(:generate_slug_based_on) do
+          [strategy, options]
+        end
+      end
+
+    end
+
+    def method_missing(missing_method, *args, &block)
+      if missing_method.to_s == "slug" && !self.methods.include?(:slug)
+        compute_slug
+      else
+        super
+      end
+    end
+
+    def compute_slug
+      strategy, options = determine_slug_generation_method
+
+      length = options[:length] if options.is_a?(Hash) || nil
+
+      if strategy == :compute_slug_based_on_attribute
+        self.send(strategy, options)
+      else
+        self.send(strategy, length)
+      end
+    end
+
+    def compute_slug_as_string(length = DEFAULT_SLUG_STRING_LENGTH)
+      length ||= DEFAULT_SLUG_STRING_LENGTH
+      (Digest::SHA2.hexdigest self.id.to_s).first(length)
+    end
+
+    def compute_slug_as_number(length = DEFAULT_SLUG_NUMBER_LENGTH)
+      length ||= DEFAULT_SLUG_NUMBER_LENGTH
+      generate_random_number_based_on_id_hex(length)
+    end
+
+    def compute_slug_based_on_attribute(attribute_name)
+      return compute_slug_as_string unless self.attributes.include?(attribute_name.to_s)
+
+      base_slug = self.send(attribute_name)&.to_s&.strip&.parameterize
+      base_slug = base_slug.presence || generate_random_number_based_on_id_hex
+
+      unique_slug = generate_unique_slug(base_slug)
+      unique_slug.presence || generate_random_number_based_on_id_hex
+    end
+
+    private
+
+    def generate_random_number_based_on_id_hex(length = DEFAULT_SLUG_NUMBER_LENGTH)
+      length ||= DEFAULT_SLUG_NUMBER_LENGTH
+      ((Digest::SHA2.hexdigest(id.to_s)).hex % (10 ** length))
+    end
+
+    def generate_unique_slug(base_slug)
+      slug_candidate = base_slug
+
+      return slug_candidate unless slug_persisted?
+
+      # Collision resolution logic:
+
+      count = 0
+
+      while self.class.exists?(slug: slug_candidate)
+        count += 1
+        # slug_candidate = "#{base_slug}-#{count}"
+        slug_candidate = "#{base_slug}-#{compute_slug_as_number}"
+      end
+
+      slug_candidate
+    end
+
+    def determine_slug_generation_method
+      return [DEFAULT_SLUG_GENERATION_STRATEGY, {}] unless respond_to?(:generate_slug_based_on)
+
+      strategy, options = generate_slug_based_on
+      options.merge!(strategy) if strategy.is_a? Hash
+
+      if strategy.is_a?(Symbol)
+        if strategy == :id
+          return [:compute_slug_as_string, options]
+        else
+          return [:compute_slug_based_on_attribute, strategy]
+        end
+      end
+
+      if strategy.is_a?(Hash)
+        if strategy.key?(:id)
+          case strategy[:id]
+          when :hex_string
+            return [:compute_slug_as_string, options]
+          when :number
+            return [:compute_slug_as_number, options]
+          else
+            return [DEFAULT_SLUG_GENERATION_STRATEGY, options]
+          end
+        elsif strategy.key?(:attribute)
+          return [:compute_slug_based_on_attribute, strategy[:attribute], options]
+        end
+      end
+
+      [DEFAULT_SLUG_GENERATION_STRATEGY, options]
+    end
+
+    def slug_persisted?
+      self.methods.include?(:slug) && self.attributes.include?("slug")
+    end
+
+    def set_slug
+      return unless slug_persisted?
+
+      self.slug = compute_slug if id_changed? || slug.blank?
+      self.save
+    end
+
+    def update_slug_if_nil
+      set_slug if slug_persisted? && self.slug.nil?
+    end
+
+  end
+end

data/lib/slugifiable/version.rb

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

data/lib/slugifiable.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "slugifiable/version"
+require_relative "slugifiable/model"
+
+module Slugifiable
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/sig/slugifiable.rbs

@@ -0,0 +1,4 @@
+module Slugifiable
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: slugifiable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- rameerez
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-10-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+description: Automatically generates unique and SEO-friendly slugs for your Rails
+  ActiveRecord model records, so you can expose them in URLs. Allows for string and
+  number-based slugs.
+email:
+- rubygems@rameerez.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/slugifiable.rb
+- lib/slugifiable/model.rb
+- lib/slugifiable/version.rb
+- sig/slugifiable.rbs
+homepage: https://github.com/rameerez/slugifiable
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rameerez/slugifiable
+  source_code_uri: https://github.com/rameerez/slugifiable
+  changelog_uri: https://github.com/rameerez/slugifiable/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.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Easily generate unique and SEO optimized slugs for your Rails ActiveRecord
+  model records, based on any attribute
+test_files: []