slimak 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 551f7dee790133d299f2990df101c7f66aa6d206932469cbfb84bd2dd7359b36
+  data.tar.gz: 07b366ca92776c71ac9e5802205ab0784358337040180ee2ed4ac81eff075894
+SHA512:
+  metadata.gz: 14414f7f4238926c9dc980caa7c9f813812409afdb1f7ebf4b36db27aa59889554db238f005304dae9990d6262565d7b7173482140a4cf24f2fcddc2e14463d4
+  data.tar.gz: 991c4c516ab9901e93ca03f9fe01aa904ca17b6e54281752966e1009fedda26f265c8b599858b927b627133b0b7c92616db7094730d57f6a16a00e66bd43b81c

data/README.md

@@ -0,0 +1,85 @@
+```markdown
+# Slimak
+
+Slimak generates slugs from multiple attributes (columns) and helps persist them to the database with uniqueness and fast lookup.
+
+Features
+- Configure which columns to include in a slug: `slug_columns :name, :assignee_name, :urgency`
+- Returns readable, parameterized slugs (uses ActiveSupport if available)
+- Optionally persists slug to a DB column (default :slug)
+- Ensures uniqueness by appending a numeric suffix when needed (e.g., `paint-the-wall`, `paint-the-wall-2`)
+- Fast lookup via `Model.find_by_slug("...")` and optional DB index/unique constraint
+- Rails Railtie automatically includes into ActiveRecord models
+
+Installation
+Add to your Gemfile:
+
+```ruby
+gem "slimak"
+```
+
+Usage (ActiveRecord)
+1) Add a slug column and index to your model's table:
+
+```ruby
+class AddSlugToTasks < ActiveRecord::Migration[6.0]
+  def change
+    add_column :tasks, :slug, :string
+    add_index  :tasks, :slug, unique: true
+    # If you scope uniqueness (e.g., per project):
+    # add_index :tasks, [:project_id, :slug], unique: true
+  end
+end
+```
+
+2) Configure the model:
+
+```ruby
+class Task < ApplicationRecord
+  include Slimak::Sluggable # is auto-included by Railtie, but explicit include is fine
+  slug_columns :name, :urgency, :assignee_name
+  # optional:
+  # slug_options column: :permalink
+  # slug_options scope: :project_id
+end
+```
+
+By default, a slug will be generated and saved before validation if the slug column is blank. If a generated slug collides with an existing record, a numeric suffix will be appended (e.g., -2, -3) until uniqueness is achieved.
+
+3) Finding by slug:
+
+```ruby
+Task.find_by_slug("paint-the-wall-2")
+# or
+Task.find_by_slug!("paint-the-wall")
+```
+
+Usage (Plain Ruby object)
+```ruby
+class FakeTask
+  include Slimak::Sluggable
+  attr_accessor :name, :urgency, :assignee_name
+  slug_columns :name, :urgency, :assignee_name
+end
+
+t = FakeTask.new
+t.name = "Paint the wall"
+t.urgency = "Critical"
+t.assignee_name = "Mark"
+t.slug # => "paint-the-wall-critical-mark"
+```
+
+Generators
+```ruby
+rails generate slimak:add_slug ModelName 
+
+Options: --column=NAME Column to add/store slug (default: slug) --scope=COLUMN_NAME Optional scope column (creates composite unique index)
+```
+
+
+Notes & Next steps
+- For robust concurrency-safe uniqueness you should also enforce a UNIQUE index in the database and handle possible race conditions (e.g., retry on unique constraint violation). Slimak already appends numeric suffixes to avoid collisions, but an index prevents races.
+- You can scope uniqueness via `slug_options scope: :project_id` and add a composite unique index [project_id, slug].
+- If you'd like, I can add a Rails generator to create migrations, or implement a DB-retry strategy to handle high concurrency collisions.
+
+```

data/Rakefile

@@ -0,0 +1,7 @@
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = "--format documentation"
+end
+
+task default: :spec

data/lib/generators/slimak/add_slug/add_slug_generator.rb

@@ -0,0 +1,58 @@
+require "rails/generators"
+require "rails/generators/migration"
+
+module Slimak
+  module Generators
+    # Usage:
+    #   rails generate slimak:add_slug ModelName --column=slug --scope=project_id --migration_version=6.1
+    class AddSlugGenerator < Rails::Generators::NamedBase
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :column, type: :string, default: "slug", desc: "Column name to store slug"
+      class_option :scope, type: :string, default: nil, desc: "Optional scope column name for scoped uniqueness"
+      class_option :migration_version, type: :string, default: nil, desc: "Rails migration version to use (e.g. 6.0). Defaults to current."
+
+      # Required by Rails::Generators::Migration to generate unique migration numbers
+      def self.next_migration_number(dirname)
+        if ActiveRecord::Base.timestamped_migrations
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+        else
+          "%.3d" % (current_migration_number(dirname) + 1)
+        end
+      end
+
+      def create_migration_file
+        migration_filename = "add_#{options['column'] || 'slug'}_to_#{file_name.pluralize}.rb"
+        migration_template "add_slug_migration.rb.erb", "db/migrate/#{migration_filename}", migration_version: migration_version_option
+      end
+
+      def create_initializer_file
+        template "slimak_initializer.rb.erb", "config/initializers/slimak.rb"
+      end
+
+      private
+
+      # prefer provided migration_version option; otherwise infer "6.0" if Rails version not available
+      def migration_version_option
+        return options["migration_version"] if options["migration_version"].present?
+        rails_major = if defined?(Rails) && Rails.respond_to?(:version)
+                        Rails.version.split(".").first(2).join(".")
+                      else
+                        "6.0"
+                      end
+        rails_major
+      end
+
+      # helper for templates
+      def column_name
+        options["column"] || "slug"
+      end
+
+      def scope_name
+        options["scope"]
+      end
+    end
+  end
+end

data/lib/generators/slimak/add_slug/templates/add_slug_migration.rb.erb

@@ -0,0 +1,10 @@
+class Add<%= (column_name + "_to_" + file_name.pluralize).camelize %> < ActiveRecord::Migration[<%= migration_version %>]
+  def change
+    add_column :<%= file_name.pluralize %>, :<%= column_name %>, :string
+    add_index  :<%= file_name.pluralize %>, :<%= column_name %>, unique: true
+<% if scope_name.present? -%>
+    # Scoped uniqueness: composite unique index on [<%= scope_name %>, :<%= column_name %>]
+    add_index :<%= file_name.pluralize %>, [:<%= scope_name %>, :<%= column_name %>], unique: true, name: "index_<%= file_name.pluralize %>_on_<%= scope_name %>_and_<%= column_name %>"
+<% end -%>
+  end
+end

data/lib/generators/slimak/add_slug/templates/slimak_initializer.rb.erb

@@ -0,0 +1,14 @@
+```ruby
+# Slimak initializer
+# Configure global defaults for Slimak gem here, for example:
+#
+# Slimak.configure do |config|
+#   config.column = :slug                    # default column name to use when generating slugs
+#   config.separator = "-"                   # default separator
+#   config.conflict_strategy = :sequence     # or :random
+#   config.random_suffix_length = 4
+#   config.slug_column_limits = { name: 20 } # global per-column limits
+# end
+#
+# Per-model configuration (slug_columns, slug_options, slug_column_limits) still overrides these defaults.
+```

data/lib/slimak/configuration.rb

@@ -0,0 +1,41 @@
+module Slimak
+  # Global configuration object for Slimak.
+  # Configure in an initializer or test with:
+  # Slimak.configure do |config|
+  #   config.separator = "_"
+  #   config.conflict_strategy = :random
+  #   config.random_suffix_length = 6
+  #   config.slug_column_limits = { name: 10 }
+  # end
+  class Configuration
+    attr_accessor :column,
+                  :separator,
+                  :conflict_strategy,
+                  :sequence_separator,
+                  :random_suffix_length,
+                  :scope,
+                  :slug_column_limits
+
+    def initialize
+      @column = :slug
+      @separator = "-"
+      @conflict_strategy = :sequence
+      @sequence_separator = "-"
+      @random_suffix_length = 4
+      @scope = nil
+      @slug_column_limits = {}
+    end
+
+    # Convert config to a plain hash used by Sluggable defaults
+    def to_hash
+      {
+        column: @column,
+        separator: @separator,
+        conflict_strategy: @conflict_strategy,
+        sequence_separator: @sequence_separator,
+        random_suffix_length: @random_suffix_length,
+        scope: @scope
+      }
+    end
+  end
+end

data/lib/slimak/railtie.rb

@@ -0,0 +1,14 @@
+# Railtie: auto-include Slimak::Sluggable into ActiveRecord::Base for Rails apps.
+if defined?(Rails)
+  require "rails/railtie"
+
+  module Slimak
+    class Railtie < ::Rails::Railtie
+      initializer "slimak.active_record" do
+        ActiveSupport.on_load(:active_record) do
+          include Slimak::Sluggable
+        end
+      end
+    end
+  end
+end

data/lib/slimak/sluggable.rb

@@ -0,0 +1,186 @@
+require "securerandom"
+
+module Slimak
+  # Sluggable concern for ActiveRecord models (also usable on plain Ruby objects).
+  module Sluggable
+    extend ActiveSupport::Concern
+
+    included do
+      if defined?(ActiveRecord) && self <= ActiveRecord::Base
+        before_validation :generate_slug_if_blank
+      end
+    end
+
+    class_methods do
+      def slug_columns(*cols)
+        @_slimak_slug_columns = cols.flatten.map(&:to_sym)
+        @_slimak_slug_column_limits ||= {}
+        @_slimak_slug_options ||= default_slug_options
+      end
+
+      def slug_column_limits(hash = nil)
+        # Merge global limits with model-specific limits; model-specific wins.
+        global = Slimak.config.slug_column_limits || {}
+        @_slimak_slug_column_limits ||= global.dup
+        if hash
+          @_slimak_slug_column_limits.merge!(hash.transform_keys(&:to_sym))
+        end
+        @_slimak_slug_column_limits
+      end
+
+      def slug_options(opts = nil)
+        @_slimak_slug_options ||= default_slug_options
+        @_slimak_slug_options.merge!(opts) if opts.is_a?(Hash)
+        @_slimak_slug_options
+      end
+
+      # Default options come from global Slimak.config so users can set global defaults.
+      def default_slug_options
+        Slimak.config.to_hash
+      end
+
+      def _slimak_slug_columns
+        @_slimak_slug_columns || []
+      end
+
+      def _slimak_slug_column_limits
+        @_slimak_slug_column_limits || Slimak.config.slug_column_limits || {}
+      end
+
+      def _slimak_slug_options
+        @_slimak_slug_options ||= default_slug_options
+      end
+
+      def find_by_slug(value)
+        col = _slimak_slug_options[:column]
+        where(col => value).first
+      end
+
+      def find_by_slug!(value)
+        find_by_slug(value) or raise ActiveRecord::RecordNotFound, "Couldn't find #{name} with slug=#{value}"
+      end
+    end
+
+    def _slug
+      col = self.class._slimak_slug_options[:column]
+      if respond_to?(col) && !send(col).to_s.strip.empty?
+        send(col).to_s
+      else
+        build_slug_string
+      end
+    end
+
+    def generate_slug_if_blank
+      return unless self.class._slimak_slug_columns.any?
+
+      slug_col = self.class._slimak_slug_options[:column]
+      if respond_to?(slug_col) && !send(slug_col).to_s.strip.empty?
+        return
+      end
+
+      candidate = build_unique_slug
+      assign_slug_column(slug_col, candidate)
+      nil
+    end
+
+    def build_slug_string
+      parts = self.class._slimak_slug_columns.map do |col|
+        v = safe_read(col)
+        next nil if v.nil?
+        formatted = format_component(v.to_s, col)
+        formatted unless formatted.to_s.empty?
+      end.compact
+
+      return "" if parts.empty?
+
+      parameterize(parts.join(" "), self.class._slimak_slug_options[:separator])
+    end
+
+    def build_unique_slug
+      base = build_slug_string
+      return base if base.to_s.strip.empty?
+      return base unless defined?(ActiveRecord) && self.class.respond_to?(:unscoped)
+
+      # Merge global options with model options so model options override global.
+      opts = Slimak.config.to_hash.merge(self.class._slimak_slug_options || {})
+      col = opts[:column]
+      scope = opts[:scope]
+
+      case opts[:conflict_strategy].to_sym
+      when :random
+        candidate = base.dup
+        while slug_exists?(candidate, col, scope)
+          suffix = SecureRandom.alphanumeric(opts[:random_suffix_length]).downcase
+          candidate = [base, suffix].join(opts[:sequence_separator])
+        end
+        candidate
+      else
+        candidate = base.dup
+        seq = 2
+        while slug_exists?(candidate, col, scope)
+          candidate = [base, seq].join(opts[:sequence_separator])
+          seq += 1
+        end
+        candidate
+      end
+    end
+
+    # Safe read helper
+    def safe_read(name)
+      if respond_to?(name)
+        send(name)
+      else
+        nil
+      end
+    rescue => _
+      nil
+    end
+
+    def format_component(str, column)
+      s = str.dup
+      s = ActiveSupport::Inflector.transliterate(s) if defined?(ActiveSupport::Inflector)
+      s = s.strip
+      limits = self.class._slimak_slug_column_limits || {}
+      max = limits && limits[column.to_sym]
+      s = s[0, max] if max && max > 0
+      s.gsub(/[[:space:]]+/, " ")
+    end
+
+    def assign_slug_column(slug_col, value)
+      if respond_to?("#{slug_col}=")
+        send("#{slug_col}=", value)
+      elsif respond_to?(:write_attribute)
+        write_attribute(slug_col, value)
+      else
+        (class << self; self; end).class_eval do
+          attr_accessor slug_col unless method_defined?(slug_col)
+        end
+        instance_variable_set("@#{slug_col}", value)
+      end
+    end
+
+    def parameterize(str, separator = "-")
+      s = str.to_s
+      begin
+        s.parameterize(separator: separator)
+      rescue ArgumentError
+        s.parameterize(separator)
+      end
+    end
+
+    def slug_exists?(candidate, col, scope)
+      return false unless defined?(ActiveRecord) && self.class.respond_to?(:unscoped)
+      rel = self.class.unscoped.where(col => candidate)
+      if scope
+        Array(scope).each do |sc|
+          val = safe_read(sc)
+          rel = rel.where(sc => val)
+        end
+      end
+      if respond_to?(:persisted?) && persisted?
+        rel = rel.where.not(id: id)
+      end
+      rel.exists?
+    end
+  end
+end

data/lib/slimak/version.rb

@@ -0,0 +1,3 @@
+module Slimak
+  VERSION = "0.2.1"
+end

data/lib/slimak.rb

@@ -0,0 +1,40 @@
+require 'logger'
+require_relative "slimak/version"
+
+# helpers from ActiveSupport for parameterize
+require "active_support"
+require "active_support/core_ext/string/inflections"
+require "active_support/inflector"
+require "active_support/concern"
+
+require_relative "slimak/configuration"
+require_relative "slimak/sluggable"
+require_relative "slimak/railtie" if defined?(Rails)
+
+module Slimak
+  # Global config object; you can reassign in tests if necessary
+  @config = Configuration.new
+
+  class << self
+    # Accessor for global config
+    def config
+      @config
+    end
+
+    # Setter for global config (useful for tests)
+    def config=(c)
+      @config = c
+    end
+
+    # Convenience configure block: Slimak.configure { |c| c.separator = "_" }
+    def configure
+      yield config if block_given?
+      config
+    end
+
+    # Reset global config to defaults
+    def reset!
+      @config = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: slimak
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Stanislaw Zawadzki
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-12-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.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: pry
+  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: Slimak creates slugs from multiple model attributes (slug_columns) and
+  supports storing them in the DB with uniqueness and fast lookup.
+email:
+- st.zawadzki@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/generators/slimak/add_slug/add_slug_generator.rb
+- lib/generators/slimak/add_slug/templates/add_slug_migration.rb.erb
+- lib/generators/slimak/add_slug/templates/slimak_initializer.rb.erb
+- lib/slimak.rb
+- lib/slimak/configuration.rb
+- lib/slimak/railtie.rb
+- lib/slimak/sluggable.rb
+- lib/slimak/version.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Multi-column slugs with ActiveRecord persistence & fast lookup
+test_files: []