shiboru 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5aaa47f5a806eacf52959e93cbd7044542e513057ee09170ff7f3e1fed5ce833
+  data.tar.gz: 907a797eb38b6a24ebf5546ca282f16021de43df7b2c6f88c7e8f01324f76d08
+SHA512:
+  metadata.gz: 356c936711fb4a648e516c2900365e8213c9e7fc2d4469cdd511e9e0ca41922cad1fde1f1f20e9f2c3fe61411272db08983d09bee47b67650e349a8ae5a86a63
+  data.tar.gz: 0d7af3c888668696ed0d219b60d43a1ea6582c8ddb16f64deb6f3fadd7949fccb09fc888c32b3f995d03ecf80fbd9030796bfa9a588b3dff21a626a488b903ac

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-09-28
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Rishi Banerjee
+
+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,352 @@
+# Shiboru
+
+DRF-style filtering for Rails APIs that feels like home to anyone coming from Django. If you’ve used [DjangoFilter](https://django-filter.readthedocs.io/), this will click instantly.
+
+Ransack exists and is great for many Rails apps, but for teams steeped in Django/DRF conventions the mental model never quite felt native. Shiboru was built to bring the DjangoFilter ergonomics to Rails: `field__op=value` params, association paths like `user__email__icontains=...`, first-class ordering and pagination, and per-model `FilterSet` classes with a sweet, explicit DSL.
+
+Maintainers: Rishi Banerjee, Pratik Jain, Nikhil Anand, Dhruv Bhargava
+
+## Features
+
+* Per-model `FilterSet` classes: `UserFilter`, `Profiles::UserFilter`, inferred from class name.
+* DRF/DjangoFilter-style operators:
+
+  * `__eq, __ne, __gt, __gte, __lt, __lte`
+  * `__contains, __icontains, __startswith, __istartswith, __endswith, __iendswith`
+  * `__in, __nin, __isnull, __range`
+* Nested association paths: `profile__city__icontains=...`, `company__name__eq=...`.
+* Ordering: `?ordering=-created_at,name`.
+* Pagination: `page/page_size` or `limit/offset`.
+* Whitelist DSL: `fields`, `related_fields`, `orderable_fields`.
+* Custom filters per resource: `filter :q { |scope, v| ... }`.
+* Postgres-friendly case-insensitive ops via `ILIKE`. Optional pg\_trgm migration for performance.
+
+## Installation
+
+Add to your Rails app:
+
+```ruby
+# Gemfile
+gem "shiboru", git: "https://github.com/your-org/shiboru" # or path: "../shiboru"
+```
+
+Install and run the installer:
+
+```bash
+bundle install
+bin/spring stop
+bin/rails g shiboru:install --pgtrgm   # --pgtrgm is safe; no-ops on non-Postgres adapters
+bin/rails db:migrate
+```
+
+The installer will create:
+
+* `config/initializers/shiboru.rb`
+* `app/filters/.keep`
+* Optionally a pg\_trgm migration guarded to run only on Postgres
+
+## Quick start
+
+Create a model:
+
+```bash
+bin/rails g model User name:string email:string:index age:integer active:boolean company:string signed_up_at:datetime
+bin/rails db:migrate
+```
+
+Generate a filter:
+
+```bash
+bin/rails g shiboru:filter UserFilter
+```
+
+Edit `app/filters/user_filter.rb`:
+
+```ruby
+# frozen_string_literal: true
+class UserFilter < Shiboru::FilterSet
+  # Model is inferred: User
+
+  fields :id, :name, :email, :age, :active, :company, :signed_up_at, :created_at, :updated_at
+  orderable_fields :name, :age, :company, :signed_up_at, :created_at
+
+  # Optional quick search (?q=...)
+  filter :q do |scope, value, context:|
+    v = "%#{value}%"
+    scope.where("users.name ILIKE ? OR users.email ILIKE ?", v, v)
+  end
+end
+```
+
+Controller and routes:
+
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  include Shiboru::Controller
+
+  def index
+    render json: api_index(User, params)   # returns {count,next,previous,results}
+  end
+end
+```
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  resources :users, only: [:index]
+end
+```
+
+Seed a little data (optional):
+
+```ruby
+# db/seeds.rb
+%w[Opmaint Acme Omnix Finlyt NovaLabs].each do |co|
+  5.times do |i|
+    User.create!(
+      name: ["Rishi Banerjee", "Pratik Jain", "Nikhil Anand", "Dhruv Bhargava"].sample + " #{i}",
+      email: "user#{i}+#{co.downcase}@example.com",
+      age: rand(18..60),
+      active: [true, false].sample,
+      company: co,
+      signed_up_at: rand(180).days.ago + rand(0..86_400)
+    )
+  end
+end
+```
+
+```bash
+bin/rails db:seed
+```
+
+Try it:
+
+```
+GET /users?name__icontains=rishi&age__gte=20&ordering=-created_at&page=1&page_size=10
+GET /users?q=bhargava
+```
+
+## The Filter DSL
+
+Shiboru looks for a `FilterSet` class named after the model: `UserFilter` for `User`, `Profiles::UserFilter` for `Profiles::User`. Place filters in `app/filters/**`.
+
+```ruby
+class ArticleFilter < Shiboru::FilterSet
+  fields :id, :title, :status, :views, :published_at, :category, :created_at
+  related_fields :user__name, :user__email, :user__company, :user__active
+  orderable_fields :published_at, :views, :created_at, :title
+
+  filter :q do |scope, value, context:|
+    v = "%#{value}%"
+    scope.where("articles.title ILIKE ? OR articles.body ILIKE ?", v, v)
+  end
+end
+```
+
+Notes:
+
+* `fields` whitelists filterable base-table columns.
+* `related_fields` whitelists association fields via `assoc__field` paths.
+* `orderable_fields` whitelists fields that can appear in `?ordering=...`.
+
+## Query language
+
+Any query param that matches `path__operator=value` becomes a filter.
+
+### Operators
+
+* Equality and comparisons: `__eq`, `__ne`, `__gt`, `__gte`, `__lt`, `__lte`
+* String matching: `__contains`, `__startswith`, `__endswith` (case sensitive)
+* Case-insensitive variants (Postgres): `__icontains`, `__istartswith`, `__iendswith`
+* Membership: `__in=1,2,3`, `__nin=4,5`
+* Null checks: `__isnull=true|false`
+* Ranges: `__range=from,to` or `from..to`
+
+Examples:
+
+```
+/users?age__gte=25&age__lt=40
+/users?email__icontains=example.com
+/users?id__in=1,2,3
+/users?signed_up_at__range=2025-01-01,2025-06-30
+```
+
+### Associations
+
+```
+/articles?user__company__eq=Acme
+/articles?user__active__eq=true&ordering=-published_at,title
+```
+
+Shiboru builds `LEFT OUTER JOIN`s for association chains. If you filter a `has_many` chain on the “one” side and see duplicates, add `distinct` at the controller level or we can enable a built-in `distinct_on_root` toggle later.
+
+## Ordering
+
+```
+?ordering=-created_at,name
+```
+
+Multiple fields are comma-separated. Use `-` for descending. Association paths are supported:
+
+```
+/articles?ordering=-user__name,views
+```
+
+## Pagination
+
+Two modes, both supported:
+
+* Page-based: `?page=2&page_size=50`
+* Offset-based: `?limit=50&offset=100`
+
+Response envelope matches DRF:
+
+```json
+{
+  "count": 421,
+  "next": 3,        // page number (or next offset in offset mode)
+  "previous": 1,    // previous page (or previous offset)
+  "results": [ ... ]
+}
+```
+
+`ENV["API_MAX_LIMIT"]` caps maximum page size and limit (default 100).
+
+## Controllers
+
+Include the helper and call `api_index(Model, params)`:
+
+```ruby
+class ArticlesController < ApplicationController
+  include Shiboru::Controller
+
+  def index
+    render json: api_index(Article, params)
+  end
+end
+```
+
+Optionally add a serializer:
+
+```ruby
+render json: api_index(Article, params, serializer: ArticleSerializer)
+```
+
+## Generators
+
+Install:
+
+```bash
+bin/rails g shiboru:install --pgtrgm
+```
+
+Create a filter:
+
+```bash
+bin/rails g shiboru:filter UserFilter
+bin/rails g shiboru:filter Articles::PostFilter   # for Articles::Post model
+```
+
+Templates live in `lib/generators/shiboru/...` inside the gem.
+
+## Performance
+
+* Add btree indexes on equality/ordering fields (`created_at`, foreign keys, etc.).
+* For `__icontains` and other case-insensitive matchers on Postgres:
+
+  * enable pg\_trgm (`--pgtrgm` in installer),
+  * create trigram indexes:
+
+    ```sql
+    CREATE EXTENSION IF NOT EXISTS pg_trgm;
+    CREATE INDEX CONCURRENTLY idx_users_name_trgm  ON users    USING gin (name gin_trgm_ops);
+    CREATE INDEX CONCURRENTLY idx_users_email_trgm ON users    USING gin (email gin_trgm_ops);
+    CREATE INDEX CONCURRENTLY idx_articles_title_trgm ON articles USING gin (title gin_trgm_ops);
+    ```
+
+## Security
+
+* The DSL is a whitelist. Only fields you declare are filterable/orderable.
+* If `related_fields` is omitted, Shiboru allows all columns on joined targets. For strict security, always declare `related_fields` explicitly.
+
+## Example: Users and Articles
+
+Models:
+
+```ruby
+class User < ApplicationRecord
+  has_many :articles, dependent: :destroy
+end
+
+class Article < ApplicationRecord
+  belongs_to :user
+end
+```
+
+Filters:
+
+```ruby
+class UserFilter < Shiboru::FilterSet
+  fields :id, :name, :email, :age, :active, :company, :signed_up_at, :created_at
+  orderable_fields :name, :age, :company, :signed_up_at, :created_at
+  filter :q do |scope, v, context:|
+    like = "%#{v}%"
+    scope.where("users.name ILIKE ? OR users.email ILIKE ?", like, like)
+  end
+end
+
+class ArticleFilter < Shiboru::FilterSet
+  fields :id, :title, :status, :views, :published_at, :category, :created_at
+  related_fields :user__name, :user__email, :user__company, :user__active
+  orderable_fields :published_at, :views, :title, :created_at
+  filter :q do |scope, v, context:|
+    like = "%#{v}%"
+    scope.where("articles.title ILIKE ? OR articles.body ILIKE ?", like, like)
+  end
+end
+```
+
+Requests:
+
+```
+/users?age__gte=25&company__eq=Acme&ordering=-signed_up_at
+/users?q=Anand&page=1&page_size=20
+
+/articles?status__in=published,archived&user__company__eq=Opmaint
+/articles?views__gte=1000&ordering=-views,title&limit=30&offset=60
+```
+
+## How it works
+
+* `Shiboru::Registry` maps `Model` → `ModelFilter` (namespaced aware).
+* `FilterSet`:
+
+  * Parses params into filter instructions (`path`, `op`, `value`).
+  * Validates against whitelists.
+  * Builds `LEFT OUTER JOIN`s for association paths.
+  * Applies `WHERE` based on operators with bind parameters.
+  * Applies `ORDER BY` and pagination.
+  * Returns a DRF-like envelope.
+
+## Why not just use Ransack?
+
+Ransack is powerful, battle-tested, and a fine choice for many Rails apps. Teams coming from Django/DRF often prefer the `field__op=value` grammar and the mental model of `FilterSet` classes that mirror the resource. Shiboru embraces that exact style so Rails APIs can feel like DRF without translation overhead.
+
+Reference: DjangoFilter documentation
+[https://django-filter.readthedocs.io/](https://django-filter.readthedocs.io/)
+
+## Development
+
+* Ruby 3.1+
+* Rails 6.1+ (tested on 7/8)
+
+Run tests:
+
+```bash
+bundle exec rspec
+```
+
+## License
+
+MIT

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: %i[spec rubocop]

data/lib/generators/shiboru/filter/filter_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Shiboru
+  module Generators
+    class FilterGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+      # Usage:
+      #   rails g shiboru:filter UserFilter
+      #   rails g shiboru:filter Profiles::UserFilter
+
+      def create_filter
+        template "filter.rb.tt", File.join("app/filters", class_path, "#{file_name}.rb")
+      end
+
+      private
+
+      def file_name = name.demodulize.underscore
+    end
+  end
+end

data/lib/generators/shiboru/filter/templates/filter.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+class <%= name %> < Shiboru::FilterSet
+  # Model is inferred from class name:
+  #   UserFilter           -> User
+  #   Profiles::UserFilter -> Profiles::User
+
+  # Base-table fields:
+  fields :id, :created_at, :updated_at
+  # fields :name, :age, ...
+
+  # Association fields as "assoc__field":
+  # related_fields :profile__city, :profile__state, :company__name
+
+  # Orderable fields:
+  orderable_fields :id, :created_at
+
+  # Custom named filter example (?active=true):
+  # filter :active do |scope, value, context:|
+  #   value.to_s == "true" ? scope.where(active: true) : scope
+  # end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Shiboru
+  module Generators
+    # Usage:
+    #   rails g shiboru:install
+    #   rails g shiboru:install --pgtrgm
+    #
+    # Creates:
+    #   config/initializers/shiboru.rb
+    #   app/filters/.keep
+    # Optionally:
+    #   db/migrate/<timestamp>_enable_pg_trgm_extension.rb  (when --pgtrgm)
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :pgtrgm, type: :boolean, default: false,
+                            desc: "Create a migration to enable pg_trgm (Postgres text search accel)"
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/shiboru.rb"
+      end
+
+      def ensure_filters_dir
+        empty_directory "app/filters"
+        create_file "app/filters/.keep" unless File.exist?("app/filters/.keep")
+      end
+
+      def create_pg_trgm_migration
+        return unless options[:pgtrgm]
+
+        unless defined?(ActiveRecord::Base)
+          say_status :warn, "ActiveRecord not found; skipping pg_trgm migration", :yellow
+          return
+        end
+
+        unless ActiveRecord::Base.connection.adapter_name.match?(/postg/i)
+          say_status :warn, "Non-Postgres adapter detected; skipping pg_trgm migration", :yellow
+          return
+        end
+
+        migration_template "enable_pg_trgm.rb.tt", "db/migrate/#{timestamp}_enable_pg_trgm_extension.rb"
+      end
+
+      private
+
+      # Basic timestamp helper for migration filenames
+      def timestamp
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      # Provide Rails' migration_template without inheriting from ActiveRecord::Generators::Base
+      def migration_template(source, destination)
+        template source, destination
+      end
+    end
+  end
+end

data/lib/generators/shiboru/install/templates/enable_pg_trgm.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+class EnablePgTrgmExtension < ActiveRecord::Migration[7.0]
+  def up
+    return unless postgres?
+
+    enable_extension "pg_trgm" unless extension_enabled?("pg_trgm")
+  end
+
+  def down
+    return unless postgres?
+
+    disable_extension "pg_trgm" if extension_enabled?("pg_trgm")
+  end
+
+  private
+
+  def postgres?
+    # Works for Rails 6/7/8, and for multiple DBs (use connection for this DB)
+    connection.adapter_name.to_s.downcase.include?("postgres")
+  end
+end

data/lib/generators/shiboru/install/templates/initializer.rb.tt

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Shiboru initializer
+#
+# Shiboru exposes a DRF-like FilterSet for Rails APIs.
+# You typically:
+#   - Create per-model filters under app/filters, e.g. UserFilter, Profiles::UserFilter
+#   - In controllers, call: render json: api_index(User, params)
+#
+# Configuration notes:
+# - Pagination limits: Shiboru reads ENV["API_MAX_LIMIT"] (default 100) to clamp page_size/limit.
+# - Postgres icontains/istartswith/iendswith use ILIKE. For fast search, consider pg_trgm.
+# - To enable pg_trgm, run installer with --pgtrgm to generate the extension migration.
+#
+# Example per-model filter:
+#   class UserFilter < Shiboru::FilterSet
+#     fields :id, :name, :age, :created_at, :updated_at
+#     related_fields :profile__city, :company__name
+#     orderable_fields :name, :age, :created_at
+#     # filter :active { |scope, v, context:| v.to_s == "true" ? scope.where(active: true) : scope }
+#   end
+#
+# Optional ENV overrides (uncomment and tune as needed):
+# ENV["API_MAX_LIMIT"] ||= "200"  # Upper cap for page_size/limit (default 100)
+
+Rails.application.config.to_prepare do
+  # Autoload filters from app/filters with Zeitwerk (Rails does this automatically if the folder exists).
+  # This block ensures any reloads pick up new filter classes in dev.
+end

data/lib/shiboru/controller.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Shiboru
+  module Controller
+    # Usage: render json: api_index(User, params, serializer: UserSerializer)
+    def api_index(model, params, serializer: nil, serializer_opts: {})
+      filter_klass = Shiboru::Registry.for_model(model)
+      raise ArgumentError, "No FilterSet found for #{model.name} (expected #{model.name}Filter)" unless filter_klass
+
+      payload = filter_klass.new(model.all, params).call
+      records = payload["results"]
+
+      payload["results"] =
+        if serializer
+          ActiveModelSerializers::SerializableResource.new(records, each_serializer: serializer,
+                                                                    **serializer_opts).as_json
+        else
+          records.as_json
+        end
+
+      payload
+    end
+  end
+end

data/lib/shiboru/filter_set.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Shiboru
+  class FilterSet
+    class << self
+      attr_reader :_fields, :_related_fields, :_orderable, :_custom_filters
+
+      # --- Sweet DSL ---
+      def fields(*names)         = (@_fields ||= []).concat(names.flatten.map(&:to_s))
+      def related_fields(*names) = (@_related_fields ||= []).concat(names.flatten.map(&:to_s))
+      def orderable_fields(*names)= (@_orderable ||= []).concat(names.flatten.map(&:to_s))
+      def filter(name, &blk) = (@_custom_filters ||= {}).store(name.to_s, blk)
+
+      # Infer model from Filter class: Profiles::UserFilter -> Profiles::User
+      def model
+        @__inferred_model ||= begin
+          base = name.sub(/Filter\z/, "")
+          raise ArgumentError, "Filter class name must end with 'Filter' (got #{name})" if base == name
+
+          constantize_chain(base)
+        end
+      end
+
+      def fields_set    = @_fields&.to_set || model.column_names.to_set
+      def related_set   = @_related_fields&.to_set || Set.new
+      def orderable_set = @_orderable&.to_set || fields_set
+      def custom_filters = @_custom_filters || {}
+
+      private
+
+      def constantize_chain(str)
+        names = str.split("::")
+        names.shift if names.first && names.first.empty?
+        constant = Object
+        names.each do |n|
+          constant = constant.const_get(n)
+        end
+        constant
+      rescue NameError => e
+        raise ArgumentError, "Cannot infer model for #{name} -> #{str}: #{e.message}"
+      end
+    end
+
+    DEFAULT_OPERATORS = Shiboru::Operators::DEFAULT
+
+    def initialize(scope, params)
+      @scope  = scope
+      @params = Shiboru::ParamParser.new(params)
+    end
+
+    def call
+      rel = apply_filters(@scope)
+      rel = apply_ordering(rel)
+      rel, meta = apply_pagination(rel)
+
+      {
+        "count" => meta[:count],
+        "next" => meta[:next],
+        "previous" => meta[:previous],
+        "results" => rel
+      }
+    end
+
+    private
+
+    def apply_filters(scope)
+      rel = scope
+
+      @params.filters.each do |f|
+        # custom named filter (?active=true)
+        if self.class.custom_filters.key?(f[:field]) && f[:assoc].empty?
+          rel = self.class.custom_filters[f[:field]].call(rel, f[:value], context: self)
+          next
+        end
+
+        if f[:assoc].empty?
+          next unless self.class.fields_set.include?(f[:field])
+
+          qualified = "#{self.class.model.table_name}.#{f[:field]}"
+          column    = self.class.model.columns_hash[f[:field]]
+          value     = cast_value(f[:op], f[:value], column)
+          sql, *b   = operator_for(f[:op]).call(qualified, value)
+          rel       = rel.where([sql, *b])
+        else
+          rel = rel.left_outer_joins(f[:assoc].map(&:to_sym))
+          target_klass = traverse_klass(self.class.model, f[:assoc])
+          next unless related_allowed?(f[:assoc], f[:field], target_klass)
+
+          qualified   = "#{target_klass.table_name}.#{f[:field]}"
+          column      = target_klass.columns_hash[f[:field]]
+          value       = cast_value(f[:op], f[:value], column)
+          sql, *b     = operator_for(f[:op]).call(qualified, value)
+          rel         = rel.where([sql, *b])
+        end
+      end
+
+      rel
+    end
+
+    def apply_ordering(scope)
+      orders = @params.ordering
+      return scope if orders.empty?
+
+      rel = scope
+      orders.each do |token|
+        dir   = token.start_with?("-") ? "DESC" : "ASC"
+        token = token.delete_prefix("-")
+        path  = token.split("__")
+        field = path.pop
+        assoc = path
+
+        if assoc.empty?
+          next unless self.class.orderable_set.include?(field)
+
+          qualified = "#{self.class.model.table_name}.#{field}"
+          rel = rel.order(Arel.sql("#{qualified} #{dir}"))
+        else
+          rel = rel.left_outer_joins(assoc.map(&:to_sym))
+          target_klass = traverse_klass(self.class.model, assoc)
+          next unless related_allowed?(assoc, field, target_klass)
+
+          qualified = "#{target_klass.table_name}.#{field}"
+          rel = rel.order(Arel.sql("#{qualified} #{dir}"))
+        end
+      end
+      rel
+    end
+
+    def apply_pagination(scope)
+      total = scope.except(:order).count(:all)
+      pg    = @params.pagination
+
+      if pg[:mode] == :page
+        page = pg[:page]
+        size = pg[:page_size]
+        offset = (page - 1) * size
+        next_page = (offset + size) < total ? page + 1 : nil
+        prev_page = page > 1 ? page - 1 : nil
+        [scope.limit(size).offset(offset), { count: total, next: next_page, previous: prev_page }]
+      else
+        limit = pg[:limit]
+        offset = pg[:offset]
+        next_offset = (offset + limit) < total ? (offset + limit) : nil
+        prev_offset = offset > 0 ? [offset - limit, 0].max : nil
+        [scope.limit(limit).offset(offset), { count: total, next: next_offset, previous: prev_offset }]
+      end
+    end
+
+    # --- helpers ---
+    def operator_for(op) = DEFAULT_OPERATORS[op] || DEFAULT_OPERATORS["eq"]
+
+    def cast_value(op, raw, column)
+      return raw if column.nil?
+
+      case op
+      when "in", "nin"
+        arr = raw.is_a?(Array) ? raw : raw.to_s.split(",")
+        arr.map { |v| cast_scalar(v, column) }
+      when "range"
+        a, b = if raw.is_a?(Array)
+                 raw
+               else
+                 (raw.to_s.include?("..") ? raw.split("..", 2) : raw.split(",", 2))
+               end
+        [cast_scalar(a, column), cast_scalar(b, column)]
+      else
+        cast_scalar(raw, column)
+      end
+    end
+
+    def cast_scalar(v, col)
+      return v if v.nil?
+
+      case col.type
+      when :integer then v.to_i
+      when :float, :decimal then v.to_f
+      when :boolean then ActiveModel::Type::Boolean.new.cast(v)
+      when :datetime, :timestamp then begin
+        Time.zone.parse(v)
+      rescue StandardError
+        v
+      end
+      when :date then begin
+        Date.parse(v)
+      rescue StandardError
+        v
+      end
+      else v
+      end
+    end
+
+    def traverse_klass(root, assoc_chain)
+      assoc_chain.reduce(root) do |klass, name|
+        refl = klass.reflect_on_association(name.to_sym)
+        raise ArgumentError, "Unknown association #{name} on #{klass.name}" unless refl
+
+        refl.klass
+      end
+    end
+
+    def related_allowed?(assoc_chain, field, target_klass)
+      return target_klass.column_names.include?(field) if self.class.related_set.empty?
+
+      token = (assoc_chain + [field]).join("__")
+      self.class.related_set.include?(token)
+    end
+  end
+end

data/lib/shiboru/operators.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Shiboru
+  module Operators
+    DEFAULT = {
+      "eq" => ->(col, v) { ["#{col} = ?", v] },
+      "ne" => ->(col, v) { ["#{col} <> ?", v] },
+      "gt" => ->(col, v) { ["#{col} > ?", v] },
+      "gte" => ->(col, v) { ["#{col} >= ?", v] },
+      "lt" => ->(col, v) { ["#{col} < ?", v] },
+      "lte" => ->(col, v) { ["#{col} <= ?", v] },
+      "contains" => ->(col, v) { ["#{col} LIKE ?", "%#{v}%"] },
+      "startswith" => ->(col, v) { ["#{col} LIKE ?", "#{v}%"] },
+      "endswith" => ->(col, v) { ["#{col} LIKE ?", "%#{v}"] },
+      "icontains" => ->(col, v) { ["#{col} ILIKE ?", "%#{v}%"] },
+      "istartswith" => ->(col, v) { ["#{col} ILIKE ?", "#{v}%"] },
+      "iendswith" => ->(col, v) { ["#{col} ILIKE ?", "%#{v}"] },
+      "in" => ->(col, v) { ["#{col} IN (?)", v] },
+      "nin" => ->(col, v) { ["#{col} NOT IN (?)", v] },
+      "isnull" => ->(col, v) { v.to_s == "true" ? ["#{col} IS NULL"] : ["#{col} IS NOT NULL"] },
+      "range" => lambda { |col, v|
+        a, b = v
+        ["#{col} BETWEEN ? AND ?", a, b]
+      }
+    }.freeze
+  end
+end

data/lib/shiboru/param_parser.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Shiboru
+  class ParamParser
+    RESERVED = %w[ordering page page_size limit offset].freeze
+
+    def initialize(params)
+      @raw = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h
+    end
+
+    def filters
+      @raw.each_with_object([]) do |(k, v), acc|
+        next if RESERVED.include?(k.to_s)
+        next if v.nil? || (v.respond_to?(:empty?) && v.empty?)
+
+        path = k.to_s.split("__")
+        op   = Shiboru::Operators::DEFAULT.key?(path.last) ? path.pop : "eq"
+        field = path.pop
+        assoc = path
+
+        acc << { assoc: assoc, field: field, op: op, value: v }
+      end
+    end
+
+    def ordering
+      (@raw["ordering"] || "").to_s.split(",").map(&:strip).reject(&:blank?)
+    end
+
+    def pagination
+      if @raw.key?("page") || @raw.key?("page_size")
+        {
+          mode: :page,
+          page: [@raw["page"].to_i, 1].max,
+          page_size: clamp((@raw["page_size"] || @raw["limit"] || 25).to_i)
+        }
+      else
+        {
+          mode: :offset,
+          limit: clamp((@raw["limit"] || 25).to_i),
+          offset: [(@raw["offset"] || 0).to_i, 0].max
+        }
+      end
+    end
+
+    private
+
+    def clamp(n)
+      max = (ENV["API_MAX_LIMIT"] || 100).to_i
+      n = 25 if n <= 0
+      [n, max].min
+    end
+  end
+end

data/lib/shiboru/railtie.rb

@@ -0,0 +1,13 @@
+# lib/shiboru/railtie.rb
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Shiboru
+  class Railtie < Rails::Railtie
+    generators do
+      require_relative "../generators/shiboru/install/install_generator"
+      require_relative "../generators/shiboru/filter/filter_generator"
+    end
+  end
+end

data/lib/shiboru/registry.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# A registry to map models to their corresponding FilterSet classes.
+module Shiboru
+  # Usage:
+  #   Shiboru::Registry.for_model(User) # => UserFilter (if UserFilter exists)
+  #   Shiboru::Registry.for_model(Post) # => PostFilter (if PostFilter exists)
+  #   Shiboru::Registry.for_model(Admin::User) # => Admin::UserFilter (if it exists)
+  #   Shiboru::Registry.for_model(NonExistentModel) # => nil (if NonExistentModelFilter doesn't exist)
+  class Registry
+    @cache = {}
+
+    class << self
+      # Given a model class, find its corresponding FilterSet class.
+      # Automatically maps model names to filter class names by appending "Filter".
+      # Results are cached to improve performance on subsequent calls.
+      #
+      # @param klass [Class] The model class to find a FilterSet for
+      # @return [Class, nil] The corresponding FilterSet class, or nil if not found
+      #
+      # Examples:
+      #   User -> UserFilter
+      #   Profiles::User -> Profiles::UserFilter
+      def for_model(klass)
+        return @cache[klass] if @cache.key?(klass)
+
+        filter_const_name = "#{klass.name}Filter"
+        filter_klass = constantize_safe(filter_const_name)
+        @cache[klass] = filter_klass
+      end
+
+      private
+
+      def constantize_safe(str)
+        names = str.split("::")
+        names.shift if names.first && names.first.empty?
+        constant = Object
+        names.each do |name|
+          return nil unless constant.const_defined?(name, false)
+
+          constant = constant.const_get(name, false)
+        end
+        constant
+      rescue NameError
+        nil
+      end
+    end
+  end
+end

data/lib/shiboru/version.rb

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

data/lib/shiboru.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "shiboru/version"
+
+require "active_support"
+require "active_support/core_ext"
+require "active_record"
+
+require "shiboru/version"
+require "shiboru/operators"
+require "shiboru/param_parser"
+require "shiboru/registry"
+require "shiboru/filter_set"
+require "shiboru/controller"
+require "shiboru/railtie"
+
+module Shiboru
+end

data/sig/shiboru.rbs

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

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: shiboru
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rishi Banerjee
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  Shiboru provides a clean and intuitive way to handle filtering, ordering, and pagination in Ruby applications.
+    It automatically maps models to filter classes, parses HTTP parameters, and supports complex nested associations with various operators.
+email:
+- rishieric91@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/shiboru/filter/filter_generator.rb
+- lib/generators/shiboru/filter/templates/filter.rb.tt
+- lib/generators/shiboru/install/install_generator.rb
+- lib/generators/shiboru/install/templates/.keep
+- lib/generators/shiboru/install/templates/enable_pg_trgm.rb.tt
+- lib/generators/shiboru/install/templates/initializer.rb.tt
+- lib/shiboru.rb
+- lib/shiboru/controller.rb
+- lib/shiboru/filter_set.rb
+- lib/shiboru/operators.rb
+- lib/shiboru/param_parser.rb
+- lib/shiboru/railtie.rb
+- lib/shiboru/registry.rb
+- lib/shiboru/version.rb
+- sig/shiboru.rbs
+homepage: https://github.com/rshrc/shiboru
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rshrc/shiboru
+  source_code_uri: https://github.com/rshrc/shiboru
+  changelog_uri: https://github.com/rshrc/shiboru/blob/main/CHANGELOG.md
+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.7.1
+specification_version: 4
+summary: A flexible filtering and pagination library for Ruby applications
+test_files: []