type_balancer_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 71cdcd571a025f512e4aafd499454b169a1fc6e0dfad5ff44ee8c673d514b978
+  data.tar.gz: 510a9017cce97a0de216d4fff5b70126bb1fcf19b4feb599df6eb529fc8b7abc
+SHA512:
+  metadata.gz: b426fdb236f4d075ae34a4b9683123d2280099117e6343f71d0dd914431d85b38131054ee9cbeb32818b75ace84000595e29f1d874f6e0e79db5240cfb19ad33
+  data.tar.gz: 92bd9e81c3fdb370c404e53d522c5e56cbadc91306002729e1ece60ac50ac5ba75f1dc5d0d8a155434a27a11948974492110bf154693f9bee7997f286bfdbb9d

data/.rubocop.yml

@@ -0,0 +1,174 @@
+require:
+  - rubocop-rspec
+  - rubocop-rails
+  - rubocop-capybara
+  - rubocop-factory_bot
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'bin/**/*'
+    - 'tmp/**/*'
+    - 'vendor/**/*'
+    - 'log/**/*'
+    - 'node_modules/**/*'
+    - 'db/schema.rb'
+    - 'db/migrate/*.rb'
+    - 'Gemfile.lock'
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/SymbolArray:
+  EnforcedStyle: brackets
+
+Style/WordArray:
+  EnforcedStyle: brackets
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/AbcSize:
+  Max: 20
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/ModuleLength:
+  Max: 200
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/VerifiedDoubles:
+  Enabled: false
+
+RSpec/MessageChain:
+  Enabled: false
+
+RSpec/NoExpectationExample:
+  Enabled: false
+
+RSpec/SubjectStub:
+  Enabled: false
+
+RSpec/StubbedMock:
+  Enabled: false
+
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/integration/**/*_spec.rb'
+
+Capybara/CurrentPathExpectation:
+  Enabled: false
+
+Capybara/MatchStyle:
+  Enabled: false
+
+Capybara/NegationMatcher:
+  Enabled: false
+
+Capybara/SpecificActions:
+  Enabled: false
+
+Capybara/SpecificFinders:
+  Enabled: false
+
+Capybara/SpecificMatcher:
+  Enabled: false
+
+Capybara/VisibilityMatcher:
+  Enabled: false
+
+FactoryBot/AttributeDefinedStatically:
+  Enabled: false
+
+FactoryBot/ConsistentParenthesesStyle:
+  Enabled: false
+
+FactoryBot/CreateList:
+  Enabled: false
+
+FactoryBot/FactoryClassName:
+  Enabled: false
+
+FactoryBot/FactoryNameStyle:
+  Enabled: false
+
+FactoryBot/SyntaxMethods:
+  Enabled: false
+
+RSpecRails/AvoidSetupHook:
+  Enabled: false
+
+RSpecRails/HaveHttpStatus:
+  Enabled: false
+
+RSpecRails/HttpStatus:
+  Enabled: false
+
+RSpecRails/InferredSpecType:
+  Enabled: false
+
+RSpecRails/MinitestAssertions:
+  Enabled: false
+
+RSpecRails/NegationBeValid:
+  Enabled: false
+
+RSpecRails/TravelAround:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 120
+
+# Disable OpenStruct warnings in specs since we use it extensively for test data
+# and the performance impact isn't relevant in our test context
+Style/OpenStructUse:
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/BlockLength:
+  Enabled: true
+  Exclude:
+    - 'spec/**/*'
+    - 'Rakefile'
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+RSpec/RepeatedExample:
+  Enabled: false # We have intentionally repeated examples
+
+RSpec/MultipleDescribes:
+  Enabled: false # We have intentionally structured our specs this way
+
+RSpec/RepeatedExampleGroupDescription:
+  Enabled: false # We have intentionally structured our specs this way
+
+# Disable Rails-specific cops since we're testing Rails integration
+Rails:
+  Enabled: false 

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-04-10
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,29 @@
+# Code of Conduct
+
+## Our Pledge
+
+We pledge to maintain a welcoming and productive environment for everyone who participates in this project, regardless of their background or experience level.
+
+## Our Standards
+
+* Be respectful of others
+* Focus on constructive contributions
+* Exercise empathy in interactions
+* Accept constructive feedback gracefully
+* Keep discussions focused on improving the project
+
+## Scope
+
+This Code of Conduct applies to all project spaces, including the repository, issue tracker, discussions, and any other project-related communication channels.
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing these standards. They have the right and responsibility to remove, edit, or reject any contributions that don't align with this Code of Conduct.
+
+## Contact
+
+If you have concerns, please contact the project maintainers.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.0. 

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Carl Smith
+
+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,96 @@
+# TypeBalancer Rails
+
+[![Gem Version](https://badge.fury.io/rb/type_balancer-rails.svg)](https://badge.fury.io/rb/type_balancer-rails)
+[![Build Status](https://github.com/llwebconsulting/type_balancer-rails/workflows/CI/badge.svg)](https://github.com/llwebconsulting/type_balancer-rails/actions)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Rails integration for the [TypeBalancer](https://github.com/llwebconsulting/type_balancer) gem. This gem provides a seamless way to balance content types in your Rails application's ActiveRecord queries.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'type_balancer-rails'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install type_balancer-rails
+```
+
+## Usage
+
+### Basic Usage
+
+The gem adds a `balance_by_type` method to your ActiveRecord relations. Here's how to use it:
+
+```ruby
+# Get a balanced collection of posts
+@posts = Post.all.balance_by_type
+
+# With pagination
+@posts = Post.all.balance_by_type.page(2).per(20)
+
+# Specify a custom type field
+@posts = Post.all.balance_by_type(type_field: :content_type)
+```
+
+### Model Configuration
+
+You can configure the default type field at the model level:
+
+```ruby
+class Post < ApplicationRecord
+  balance_by_type type_field: :content_type
+end
+
+# Now you can call without specifying the type field
+@posts = Post.all.balance_by_type
+
+# You can still override the type field per query
+@posts = Post.all.balance_by_type(type_field: :category)
+```
+
+### Chainable with ActiveRecord
+
+The `balance_by_type` method preserves the ActiveRecord query interface:
+
+```ruby
+@posts = Post.where(published: true)
+             .order(created_at: :desc)
+             .balance_by_type
+             .page(2)
+             .per(20)
+```
+
+## 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
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/llwebconsulting/type_balancer-rails.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the TypeBalancer Rails project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: [:spec, :rubocop]

data/lib/generators/type_balancer/install/install_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module TypeBalancer
+  module Generators
+    # Generator for installing TypeBalancer::Rails
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def create_initializer
+        template(
+          'type_balancer.rb.erb',
+          'config/initializers/type_balancer.rb'
+        )
+      end
+    end
+  end
+end

data/lib/generators/type_balancer/install/templates/type_balancer.rb.erb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+TypeBalancer::Rails.configure do |config|
+  # Duration to cache balanced positions
+  config.cache_duration = 1.hour
+
+  # Collection size threshold for background processing
+  config.async_threshold = 1000
+
+  # Default number of items per page
+  config.per_page_default = 25
+
+  # Maximum number of items per page
+  config.max_per_page = 100
+end 

data/lib/type_balancer/rails/active_record_extension.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module TypeBalancer
+  module Rails
+    # Extension for ActiveRecord models to configure type balancing
+    module ActiveRecordExtension
+      extend ActiveSupport::Concern
+
+      included do
+        class << self
+          def all
+            relation = super
+            relation.extend(TypeBalancer::Rails::CollectionMethods)
+            relation
+          end
+        end
+      end
+
+      class_methods do
+        def balance_by_type(options = {})
+          self.type_balancer_options = {
+            type_field: options[:type_field] || :type
+          }
+
+          return [] unless respond_to?(:all)
+
+          relation = all
+          return [] unless relation.is_a?(ActiveRecord::Relation)
+
+          relation.extend(CollectionMethods)
+          relation.balance_by_type(options)
+        end
+
+        def type_balancer_options
+          @type_balancer_options ||= {}
+        end
+
+        attr_writer :type_balancer_options
+      end
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  extend TypeBalancer::Rails::ActiveRecordExtension
+end

data/lib/type_balancer/rails/collection_methods.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  module Rails
+    # Provides collection methods for balancing by type
+    # These methods are extended onto ActiveRecord::Relation
+    module CollectionMethods
+      # Public: Balance the collection by type
+      #
+      # options - Hash of options to merge with model's type_balancer_options (default: {})
+      #          :type_field - Field to balance by (default: :type)
+      #          :page      - Page number for pagination (default: 1)
+      #          :per_page  - Number of items per page (default: 20)
+      #
+      # Examples
+      #
+      #   Post.all.balance_by_type
+      #   Post.where(published: true).balance_by_type(type_field: :category)
+      #   Post.all.balance_by_type(page: 2, per_page: 20)
+      #
+      # Returns ActiveRecord::Relation with balanced ordering
+      def balance_by_type(options = {})
+        records = to_a
+        return empty_relation if records.empty?
+
+        # Get type field from options or model configuration
+        type_field = fetch_type_field(options)
+
+        # Balance records using TypeBalancer
+        balanced = TypeBalancer.balance(records, type_field: type_field)
+        return empty_relation if balanced.nil?
+
+        # Handle pagination if requested
+        if options[:page] || options[:per_page]
+          page = (options[:page] || 1).to_i
+          per_page = (options[:per_page] || 20).to_i
+          offset = (page - 1) * per_page
+          balanced = balanced[offset, per_page] || []
+        end
+
+        # Return as relation
+        TestRelation.new(balanced)
+      end
+
+      def all_records = to_a
+
+      private
+
+      def empty_relation
+        TestRelation.new([])
+      end
+
+      def fetch_type_field(options)
+        model_opts = klass.respond_to?(:type_balancer_options) ? klass.type_balancer_options : {}
+        options[:type_field] || model_opts[:type_field] || :type
+      end
+    end
+  end
+end

data/lib/type_balancer/rails/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer 'type_balancer.configure_rails_initialization' do
+        # Include the ActiveRecord extension
+        ActiveSupport.on_load(:active_record) do
+          include TypeBalancer::Rails::ActiveRecordExtension
+        end
+      end
+    end
+  end
+end

data/lib/type_balancer/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  module Rails
+    VERSION = '0.1.0'
+  end
+end

data/lib/type_balancer/rails.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext'
+require 'active_record'
+
+require_relative 'rails/active_record_extension'
+require_relative 'rails/collection_methods'
+
+module TypeBalancer
+  module Rails
+  end
+end

data/lib/type_balancer_rails.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext'
+require 'active_record'
+require 'type_balancer'
+
+require_relative 'type_balancer/rails/version'
+require_relative 'type_balancer/rails'
+require 'type_balancer/rails/collection_methods'

data/type_balancer_rails.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'lib/type_balancer/rails/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'type_balancer_rails'
+  spec.version = TypeBalancer::Rails::VERSION
+  spec.authors = ['Carl Smith']
+  spec.email = ['carl@llwebconsulting.com']
+
+  spec.summary = 'Rails integration for type_balancer'
+  spec.description = 'Provides Rails integration for the type_balancer gem'
+  spec.homepage = 'https://github.com/llwebconsulting/type_balancer-rails'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?('bin/', 'test/', 'spec/', 'features/', '.git', '.circleci', 'appveyor', 'Gemfile')
+    end
+  end
+  spec.require_paths = ['lib']
+
+  # Runtime dependencies
+  spec.add_dependency 'activerecord', '~> 7.0'
+  spec.add_dependency 'activesupport', '~> 7.0'
+  spec.add_dependency 'type_balancer', '~> 0.1', '>= 0.1.0'
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: type_balancer_rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Carl Smith
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-04-26 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'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: type_balancer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: Provides Rails integration for the type_balancer gem
+email:
+- carl@llwebconsulting.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/type_balancer/install/install_generator.rb
+- lib/generators/type_balancer/install/templates/type_balancer.rb.erb
+- lib/type_balancer/rails.rb
+- lib/type_balancer/rails/active_record_extension.rb
+- lib/type_balancer/rails/collection_methods.rb
+- lib/type_balancer/rails/railtie.rb
+- lib/type_balancer/rails/version.rb
+- lib/type_balancer_rails.rb
+- type_balancer_rails.gemspec
+homepage: https://github.com/llwebconsulting/type_balancer-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/llwebconsulting/type_balancer-rails
+  source_code_uri: https://github.com/llwebconsulting/type_balancer-rails
+  changelog_uri: https://github.com/llwebconsulting/type_balancer-rails/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+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.18
+signing_key:
+specification_version: 4
+summary: Rails integration for type_balancer
+test_files: []