scopa 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e5b9095e2a8d90b5c238dd20baeac0c9e05059eb9b3b964acc26117a70ff292
+  data.tar.gz: 631337ffbfe9d49b350800e95b9117416b06f66b9b2e377f93aff790f3df4b1e
+SHA512:
+  metadata.gz: 2c5aee42cfbd651e499af3886e261544aea43eb2a1b26b030f781440cfb0ddb51a394ac634f2347d44892056ca11c9b930c37b86400e7c6ba98a6b9832a2ec22
+  data.tar.gz: 97079279d28c3828607040efdba39dc31c673dd8496214f4606627e1c004d4669ad6c5bce9648793eea3a0d1e36913277425d513ea3ceb75ad4dc3ca3ccf5ead

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [1.0.0] - 2026-01-17
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joshmn
+
+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,198 @@
+# Scopa
+
+Query objects for Rails. Encapsulate complex queries with validated parameters and composable filters.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "scopa"
+```
+
+## What it does
+
+Scopa gives you a structured way to build query objects. You define parameters with types and validations, compose filters that apply conditionally, and get instrumentation out of the box.
+
+```ruby
+class Users::ActiveQuery < Scopa::Base
+  model User
+
+  parameter :role, optional: true
+  parameter :created_after, :date, optional: true
+
+  filter(:active) { |scope| scope.where(active: true) }
+  filter(:by_role, if: :role) { |scope| scope.where(role: role) }
+  filter(:recent, if: :created_after) { |scope| scope.where("created_at > ?", created_after) }
+end
+
+Users::ActiveQuery.call(role: :admin)
+# => User.where(active: true).where(role: :admin)
+
+Users::ActiveQuery.call
+# => User.where(active: true)
+```
+
+## Parameters
+
+Parameters define the inputs your query accepts. They support types, defaults, and validation.
+
+### Basic parameters
+
+```ruby
+parameter :status
+```
+
+Required by default. The query raises `Scopa::InvalidError` if called without it.
+
+### Optional parameters
+
+```ruby
+parameter :search, optional: true
+```
+
+### Typed parameters
+
+Uses ActiveModel's attribute types for coercion:
+
+```ruby
+parameter :limit, :integer, default: 25
+parameter :include_archived, :boolean, default: false
+parameter :start_date, :date, optional: true
+```
+
+String `"10"` becomes integer `10`. String `"true"` becomes boolean `true`.
+
+### Dynamic defaults
+
+Pass a proc for defaults that need to be evaluated at call time:
+
+```ruby
+parameter :since, :datetime, default: -> { 1.week.ago }
+```
+
+The proc runs in the context of the query instance, so it has access to other parameters.
+
+## Filters
+
+Filters transform the scope. They run in definition order.
+
+### Unconditional filters
+
+Always applied:
+
+```ruby
+filter(:published) { |scope| scope.where(published: true) }
+filter(:ordered) { |scope| scope.order(created_at: :desc) }
+```
+
+### Conditional filters
+
+Applied only when a condition is met.
+
+**Symbol condition** checks if the parameter is present:
+
+```ruby
+parameter :category_id, optional: true
+
+filter(:by_category, if: :category_id) { |scope| scope.where(category_id: category_id) }
+```
+
+**Proc condition** for more complex logic:
+
+```ruby
+parameter :min_price, :decimal, optional: true
+parameter :max_price, :decimal, optional: true
+
+filter(:price_range, if: -> { min_price.present? || max_price.present? }) do |scope|
+  scope = scope.where("price >= ?", min_price) if min_price.present?
+  scope = scope.where("price <= ?", max_price) if max_price.present?
+  scope
+end
+```
+
+Filters have access to all parameter values as instance methods.
+
+## Handling invalid parameters
+
+By default, calling a query with invalid parameters raises `Scopa::InvalidError`. You can change this:
+
+```ruby
+class SearchQuery < Scopa::Base
+  model Product
+  on_invalid :return_none  # returns Product.none instead of raising
+
+  parameter :query
+end
+
+SearchQuery.call  # => Product.none (no exception)
+```
+
+Options:
+
+- `:raise` (default) raises `Scopa::InvalidError`
+- `:return_none` returns `Model.none`
+- `:ignore` runs the query anyway, skipping validation.
+
+## Custom scopes
+
+By default, queries start from `Model.all`. Pass a custom scope to narrow the base:
+
+```ruby
+Users::ActiveQuery.call(scope: current_account.users, role: :admin)
+# Starts from current_account.users instead of User.all
+```
+
+## Inheritance
+
+Query classes can inherit from other query classes. Filters, parameters, and configuration are inherited and can be extended:
+
+```ruby
+class BaseQuery < Scopa::Base
+  model User
+  filter(:active) { |scope| scope.where(active: true) }
+end
+
+class AdminQuery < BaseQuery
+  filter(:admins) { |scope| scope.where(role: :admin) }
+end
+
+AdminQuery.call
+# => User.where(active: true).where(role: :admin)
+```
+
+Child classes can override `on_invalid` and add their own parameters without affecting the parent.
+
+## Instrumentation
+
+Every query call emits an `ActiveSupport::Notifications` event:
+
+```ruby
+ActiveSupport::Notifications.subscribe("scopa.call") do |event|
+  Rails.logger.info "#{event.payload[:query_class]} took #{event.duration}ms"
+  Rails.logger.debug "Params: #{event.payload[:params]}"
+end
+```
+
+Payload includes:
+
+- `query_class` the name of the query class
+- `params` the parameter values passed to the query
+
+## Rails integration
+
+In Rails, Scopa automatically adds `app/queries` to the autoload paths. Create query classes there:
+
+```
+app/
+  queries/
+    users/
+      active_query.rb
+      search_query.rb
+    orders/
+      pending_query.rb
+```
+
+## License
+
+MIT

data/Rakefile

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

data/lib/scopa/base.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Scopa
+  class Base
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include ActiveModel::Validations
+
+    class_attribute :_model, instance_writer: false
+    class_attribute :_filters, instance_writer: false, default: []
+    class_attribute :_on_invalid, instance_writer: false, default: :raise
+    class_attribute :_parameters, instance_writer: false, default: {}
+
+    class << self
+      def inherited(subclass)
+        super
+        subclass._filters = _filters.dup
+        subclass._parameters = _parameters.dup
+      end
+
+      def model(klass = nil)
+        if klass
+          self._model = klass
+        else
+          _model
+        end
+      end
+
+      def parameter(name, type = nil, default: nil, optional: false)
+        _parameters[name] = { default: default, optional: optional }
+
+        if default.respond_to?(:call)
+          attribute name, type
+          define_method(name) do
+            value = super()
+            return value unless value.nil?
+            instance_exec(&self.class._parameters[name][:default])
+          end
+        else
+          attribute name, type, default: default
+        end
+
+        validates name, presence: true unless optional
+      end
+
+      def filter(name, if: nil, &block)
+        self._filters = _filters + [Filter.new(name, condition: binding.local_variable_get(:if), block: block)]
+      end
+
+      def on_invalid(behavior)
+        self._on_invalid = behavior
+      end
+
+      def call(scope: nil, **params)
+        new(scope: scope, **params).call
+      end
+    end
+
+    attr_reader :scope
+
+    def initialize(scope: nil, **params)
+      @scope = scope
+      super(**params)
+    end
+
+    def call
+      return handle_invalid unless valid?
+
+      instrument do
+        _filters.reduce(base_scope) do |relation, filter|
+          apply_filter(filter, relation)
+        end
+      end
+    end
+
+    private
+
+    def base_scope
+      @scope || _model.all
+    end
+
+    def apply_filter(filter, relation)
+      return relation unless filter_applies?(filter)
+      instance_exec(relation, &filter.block)
+    end
+
+    def filter_applies?(filter)
+      return true unless filter.condition
+
+      case filter.condition
+      when Symbol
+        value = send(filter.condition)
+        value.present?
+      when Proc
+        instance_exec(&filter.condition)
+      else
+        filter.condition
+      end
+    end
+
+    def handle_invalid
+      case _on_invalid
+      when :raise
+        raise InvalidError.new(errors.full_messages)
+      when :return_none
+        _model.none
+      when :ignore
+        call_without_validation
+      end
+    end
+
+    def call_without_validation
+      instrument do
+        _filters.reduce(base_scope) do |relation, filter|
+          apply_filter(filter, relation)
+        end
+      end
+    end
+
+    def instrument(&block)
+      Scopa::Instrumentation.instrument(self.class.name, attributes, &block)
+    end
+  end
+end

data/lib/scopa/filter.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Scopa
+  class Filter
+    attr_reader :name, :condition, :block
+
+    def initialize(name, condition:, block:)
+      @name = name
+      @condition = condition
+      @block = block
+    end
+  end
+end

data/lib/scopa/instrumentation.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module Scopa
+  module Instrumentation
+    def self.instrument(query_class, params, &block)
+      ActiveSupport::Notifications.instrument("scopa.call", query_class: query_class, params: params, &block)
+    end
+  end
+end

data/lib/scopa/invalid_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Scopa
+  class InvalidError < StandardError
+    attr_reader :errors
+
+    def initialize(errors = [])
+      @errors = errors
+      super(errors.join(", "))
+    end
+  end
+end

data/lib/scopa/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Scopa
+  class Railtie < Rails::Railtie
+    initializer "scopa.add_autoload_paths" do |app|
+      app.config.autoload_paths << Rails.root.join("app", "queries")
+      app.config.eager_load_paths << Rails.root.join("app", "queries")
+    end
+  end
+end

data/lib/scopa/version.rb

@@ -0,0 +1,3 @@
+module Scopa
+  VERSION = "1.0.0"
+end

data/lib/scopa.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/object/blank"
+
+require_relative "scopa/version"
+require_relative "scopa/invalid_error"
+require_relative "scopa/filter"
+require_relative "scopa/instrumentation"
+require_relative "scopa/base"
+
+module Scopa
+  class Error < StandardError; end
+
+  def self.instrument(query_class, params, &block)
+    Instrumentation.instrument(query_class, params, &block)
+  end
+end
+
+require_relative "scopa/railtie" if defined?(Rails::Railtie)

data/spec/scopa/base_spec.rb

@@ -0,0 +1,465 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Scopa::Base do
+  describe ".model" do
+    it "sets the model for the query" do
+      query_class = Class.new(described_class) do
+        model MockModel
+      end
+
+      expect(query_class.model).to eq(MockModel)
+    end
+  end
+
+  describe ".parameter" do
+    describe "with static default" do
+      it "uses the default value when not provided" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :status, default: :active
+          filter(:noop) { |r| r }
+        end
+
+        query = query_class.new
+
+        expect(query.status).to eq(:active)
+      end
+
+      it "allows overriding the default" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :status, default: :active
+          filter(:noop) { |r| r }
+        end
+
+        query = query_class.new(status: :inactive)
+
+        expect(query.status).to eq(:inactive)
+      end
+    end
+
+    describe "with proc default" do
+      it "evaluates the proc fresh on each call" do
+        call_count = 0
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :counter, default: -> { call_count += 1 }
+          filter(:noop) { |r| r }
+        end
+
+        first = query_class.new.counter
+        second = query_class.new.counter
+
+        expect(first).to eq(1)
+        expect(second).to eq(2)
+      end
+
+      it "allows overriding the proc default" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :time, default: -> { Time.now }
+          filter(:noop) { |r| r }
+        end
+
+        frozen_time = Time.new(2020, 1, 1)
+        query = query_class.new(time: frozen_time)
+
+        expect(query.time).to eq(frozen_time)
+      end
+    end
+
+    describe "required parameters" do
+      it "fails validation when required param is missing" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :required_param
+          filter(:noop) { |r| r }
+        end
+
+        query = query_class.new
+
+        expect(query).not_to be_valid
+      end
+
+      it "passes validation when required param is present" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :required_param
+          filter(:noop) { |r| r }
+        end
+
+        query = query_class.new(required_param: "value")
+
+        expect(query).to be_valid
+      end
+    end
+
+    describe "optional parameters" do
+      it "passes validation when optional param is missing" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :optional_param, optional: true
+          filter(:noop) { |r| r }
+        end
+
+        query = query_class.new
+
+        expect(query).to be_valid
+      end
+    end
+
+    describe "with type" do
+      it "coerces string to integer" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :limit, :integer, default: 10
+          filter(:noop) { |r| r }
+        end
+
+        query = query_class.new(limit: "25")
+
+        expect(query.limit).to eq(25)
+      end
+
+      it "coerces string to boolean" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :active, :boolean, default: false
+          filter(:noop) { |r| r }
+        end
+
+        query = query_class.new(active: "true")
+
+        expect(query.active).to be true
+      end
+
+      it "coerces to string" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :name, :string, default: "default"
+          filter(:noop) { |r| r }
+        end
+
+        query = query_class.new(name: 123)
+
+        expect(query.name).to eq("123")
+      end
+
+      it "works with type and proc default" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :count, :integer, default: -> { 5 + 5 }
+          filter(:noop) { |r| r }
+        end
+
+        query = query_class.new
+
+        expect(query.count).to eq(10)
+      end
+
+      it "coerces value when overriding proc default" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :count, :integer, default: -> { 10 }
+          filter(:noop) { |r| r }
+        end
+
+        query = query_class.new(count: "42")
+
+        expect(query.count).to eq(42)
+      end
+    end
+  end
+
+  describe ".filter" do
+    it "applies filters to the base scope" do
+      query_class = Class.new(described_class) do
+        model MockModel
+        filter(:active) { |r| r.where(active: true) }
+      end
+
+      result = query_class.call
+
+      expect(result.applied_filters).to include(where: { active: true })
+    end
+
+    it "applies multiple filters in definition order" do
+      query_class = Class.new(described_class) do
+        model MockModel
+        filter(:first) { |r| r.where(first: true) }
+        filter(:second) { |r| r.where(second: true) }
+      end
+
+      result = query_class.call
+
+      expect(result.applied_filters).to eq([
+        { where: { first: true } },
+        { where: { second: true } }
+      ])
+    end
+
+    it "has access to parameter values" do
+      query_class = Class.new(described_class) do
+        model MockModel
+        parameter :status, default: :active
+        filter(:by_status) { |r| r.where(status: status) }
+      end
+
+      result = query_class.call(status: :pending)
+
+      expect(result.applied_filters).to include(where: { status: :pending })
+    end
+  end
+
+  describe ".filter with conditional" do
+    describe "symbol condition" do
+      it "applies filter when param is present" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :role, optional: true
+          filter(:by_role, if: :role) { |r| r.where(role: role) }
+        end
+
+        result = query_class.call(role: :admin)
+
+        expect(result.applied_filters).to include(where: { role: :admin })
+      end
+
+      it "skips filter when param is nil" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :role, optional: true
+          filter(:by_role, if: :role) { |r| r.where(role: role) }
+        end
+
+        result = query_class.call
+
+        expect(result.applied_filters).to be_empty
+      end
+
+      it "skips filter when param is blank" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :role, optional: true
+          filter(:by_role, if: :role) { |r| r.where(role: role) }
+        end
+
+        result = query_class.call(role: "")
+
+        expect(result.applied_filters).to be_empty
+      end
+    end
+
+    describe "proc condition" do
+      it "applies filter when proc returns true" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :count, default: 5
+          filter(:expensive, if: -> { count > 3 }) { |r| r.where(expensive: true) }
+        end
+
+        result = query_class.call
+
+        expect(result.applied_filters).to include(where: { expensive: true })
+      end
+
+      it "skips filter when proc returns false" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :count, default: 1
+          filter(:expensive, if: -> { count > 3 }) { |r| r.where(expensive: true) }
+        end
+
+        result = query_class.call
+
+        expect(result.applied_filters).to be_empty
+      end
+    end
+  end
+
+  describe ".on_invalid" do
+    describe ":raise (default)" do
+      it "raises InvalidError when validation fails" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :required
+          filter(:noop) { |r| r }
+
+          def self.name
+            "TestQuery"
+          end
+        end
+
+        expect { query_class.call }.to raise_error(Scopa::InvalidError)
+      end
+
+      it "includes error messages in the exception" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          parameter :required
+          filter(:noop) { |r| r }
+
+          def self.name
+            "TestQuery"
+          end
+        end
+
+        expect { query_class.call }.to raise_error do |error|
+          expect(error.errors).to include(/can't be blank/)
+        end
+      end
+    end
+
+    describe ":return_none" do
+      it "returns model.none when validation fails" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          on_invalid :return_none
+          parameter :required
+          filter(:noop) { |r| r }
+        end
+
+        result = query_class.call
+
+        expect(result.instance_variable_get(:@none)).to be true
+      end
+    end
+
+    describe ":ignore" do
+      it "runs query despite invalid params" do
+        query_class = Class.new(described_class) do
+          model MockModel
+          on_invalid :ignore
+          parameter :required
+          filter(:always) { |r| r.where(always: true) }
+        end
+
+        result = query_class.call
+
+        expect(result.applied_filters).to include(where: { always: true })
+      end
+    end
+  end
+
+  describe ".call with scope" do
+    it "uses the provided scope instead of model.all" do
+      custom_scope = MockRelation.new([], [{ where: { account_id: 1 } }])
+      query_class = Class.new(described_class) do
+        model MockModel
+        filter(:active) { |r| r.where(active: true) }
+      end
+
+      result = query_class.call(scope: custom_scope)
+
+      expect(result.applied_filters).to eq([
+        { where: { account_id: 1 } },
+        { where: { active: true } }
+      ])
+    end
+  end
+
+  describe "inheritance" do
+    it "inherits model from parent" do
+      parent = Class.new(described_class) do
+        model MockModel
+      end
+      child = Class.new(parent)
+
+      expect(child.model).to eq(MockModel)
+    end
+
+    it "allows child to override model" do
+      other_model = Class.new(MockModel)
+      parent = Class.new(described_class) do
+        model MockModel
+      end
+      child = Class.new(parent) do
+        model other_model
+      end
+
+      expect(child.model).to eq(other_model)
+    end
+
+    it "inherits filters from parent" do
+      parent = Class.new(described_class) do
+        model MockModel
+        filter(:parent_filter) { |r| r.where(parent: true) }
+      end
+      child = Class.new(parent) do
+        filter(:child_filter) { |r| r.where(child: true) }
+      end
+
+      result = child.call
+
+      expect(result.applied_filters).to eq([
+        { where: { parent: true } },
+        { where: { child: true } }
+      ])
+    end
+
+    it "does not modify parent filters when child adds filters" do
+      parent = Class.new(described_class) do
+        model MockModel
+        filter(:parent_filter) { |r| r.where(parent: true) }
+      end
+      Class.new(parent) do
+        filter(:child_filter) { |r| r.where(child: true) }
+      end
+
+      result = parent.call
+
+      expect(result.applied_filters).to eq([{ where: { parent: true } }])
+    end
+
+    it "inherits parameters from parent" do
+      parent = Class.new(described_class) do
+        model MockModel
+        parameter :inherited_param, default: :from_parent
+        filter(:noop) { |r| r }
+      end
+      child = Class.new(parent)
+
+      query = child.new
+
+      expect(query.inherited_param).to eq(:from_parent)
+    end
+
+    it "inherits on_invalid behavior from parent" do
+      parent = Class.new(described_class) do
+        model MockModel
+        on_invalid :return_none
+        parameter :required
+        filter(:noop) { |r| r }
+      end
+      child = Class.new(parent)
+
+      result = child.call
+
+      expect(result.instance_variable_get(:@none)).to be true
+    end
+
+    it "allows child to override on_invalid behavior" do
+      parent = Class.new(described_class) do
+        model MockModel
+        on_invalid :return_none
+        parameter :required
+        filter(:noop) { |r| r }
+
+        def self.name
+          "ParentQuery"
+        end
+      end
+      child = Class.new(parent) do
+        on_invalid :raise
+
+        def self.name
+          "ChildQuery"
+        end
+      end
+
+      expect { child.call }.to raise_error(Scopa::InvalidError)
+    end
+  end
+end

data/spec/scopa/filter_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Scopa::Filter do
+  describe "#initialize" do
+    it "stores the name" do
+      filter = described_class.new(:by_status, condition: nil, block: -> {})
+
+      expect(filter.name).to eq(:by_status)
+    end
+
+    it "stores the condition" do
+      condition = :role
+      filter = described_class.new(:by_role, condition: condition, block: -> {})
+
+      expect(filter.condition).to eq(:role)
+    end
+
+    it "stores the block" do
+      block = ->(r) { r.where(active: true) }
+      filter = described_class.new(:active, condition: nil, block: block)
+
+      expect(filter.block).to eq(block)
+    end
+  end
+end

data/spec/scopa/instrumentation_spec.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Scopa::Instrumentation do
+  describe ".instrument" do
+    it "publishes scopa.call event" do
+      events = []
+      ActiveSupport::Notifications.subscribe("scopa.call") do |event|
+        events << event
+      end
+
+      described_class.instrument("TestQuery", { status: :active }) { "result" }
+
+      expect(events.length).to eq(1)
+    ensure
+      ActiveSupport::Notifications.unsubscribe("scopa.call")
+    end
+
+    it "includes query_class in payload" do
+      payload = nil
+      ActiveSupport::Notifications.subscribe("scopa.call") do |event|
+        payload = event.payload
+      end
+
+      described_class.instrument("Users::ActiveQuery", {}) { "result" }
+
+      expect(payload[:query_class]).to eq("Users::ActiveQuery")
+    ensure
+      ActiveSupport::Notifications.unsubscribe("scopa.call")
+    end
+
+    it "includes params in payload" do
+      payload = nil
+      ActiveSupport::Notifications.subscribe("scopa.call") do |event|
+        payload = event.payload
+      end
+
+      described_class.instrument("TestQuery", { status: :active, limit: 10 }) { "result" }
+
+      expect(payload[:params]).to eq({ status: :active, limit: 10 })
+    ensure
+      ActiveSupport::Notifications.unsubscribe("scopa.call")
+    end
+
+    it "returns the block result" do
+      result = described_class.instrument("TestQuery", {}) { "query result" }
+
+      expect(result).to eq("query result")
+    end
+
+    it "measures duration" do
+      duration = nil
+      ActiveSupport::Notifications.subscribe("scopa.call") do |event|
+        duration = event.duration
+      end
+
+      described_class.instrument("TestQuery", {}) { sleep(0.01) }
+
+      expect(duration).to be >= 10
+    ensure
+      ActiveSupport::Notifications.unsubscribe("scopa.call")
+    end
+  end
+end
+
+RSpec.describe "Scopa instrumentation integration" do
+  it "instruments calls through Scopa::Base" do
+    events = []
+    ActiveSupport::Notifications.subscribe("scopa.call") do |event|
+      events << event
+    end
+
+    query_class = Class.new(Scopa::Base) do
+      model MockModel
+      parameter :status, default: :active
+      filter(:by_status) { |r| r.where(status: status) }
+
+      def self.name
+        "TestQuery"
+      end
+    end
+
+    query_class.call
+
+    expect(events.length).to eq(1)
+    expect(events.first.payload[:query_class]).to eq("TestQuery")
+  ensure
+    ActiveSupport::Notifications.unsubscribe("scopa.call")
+  end
+end

data/spec/scopa/invalid_error_spec.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Scopa::InvalidError do
+  describe "#initialize" do
+    it "stores the errors" do
+      error = described_class.new(["Name can't be blank", "Email is invalid"])
+
+      expect(error.errors).to eq(["Name can't be blank", "Email is invalid"])
+    end
+
+    it "sets message from joined errors" do
+      error = described_class.new(["Name can't be blank", "Email is invalid"])
+
+      expect(error.message).to eq("Name can't be blank, Email is invalid")
+    end
+  end
+
+  it "is a StandardError" do
+    expect(described_class.ancestors).to include(StandardError)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scopa"
+
+Dir[File.join(__dir__, "support", "**", "*.rb")].each { |f| require f }
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.filter_run_when_matching :focus
+  config.disable_monkey_patching!
+  config.warnings = true
+
+  config.default_formatter = "doc" if config.files_to_run.one?
+
+  config.order = :random
+  Kernel.srand config.seed
+end

data/spec/support/mock_model.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class MockRelation
+  attr_reader :records, :applied_filters
+
+  def initialize(records = [], applied_filters = [])
+    @records = records
+    @applied_filters = applied_filters
+  end
+
+  def where(conditions)
+    MockRelation.new(records, applied_filters + [{ where: conditions }])
+  end
+
+  def joins(*tables)
+    MockRelation.new(records, applied_filters + [{ joins: tables }])
+  end
+
+  def having(*args)
+    MockRelation.new(records, applied_filters + [{ having: args }])
+  end
+
+  def group(*columns)
+    MockRelation.new(records, applied_filters + [{ group: columns }])
+  end
+
+  def distinct
+    MockRelation.new(records, applied_filters + [{ distinct: true }])
+  end
+
+  def to_a
+    records
+  end
+end
+
+class MockModel
+  class << self
+    def all
+      MockRelation.new
+    end
+
+    def none
+      MockRelation.new.tap do |r|
+        r.instance_variable_set(:@none, true)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: scopa
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Josh
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  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'
+description: Scopa provides a clean DSL for building query objects in Rails applications.
+  Define parameters with types and validations, compose filters conditionally, and
+  instrument query execution.
+email:
+- joshdotmn@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/scopa.rb
+- lib/scopa/base.rb
+- lib/scopa/filter.rb
+- lib/scopa/instrumentation.rb
+- lib/scopa/invalid_error.rb
+- lib/scopa/railtie.rb
+- lib/scopa/version.rb
+- spec/scopa/base_spec.rb
+- spec/scopa/filter_spec.rb
+- spec/scopa/instrumentation_spec.rb
+- spec/scopa/invalid_error_spec.rb
+- spec/spec_helper.rb
+- spec/support/mock_model.rb
+homepage: https://github.com/joshmn/scopa
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/joshmn/scopa
+  source_code_uri: https://github.com/joshmn/scopa
+  changelog_uri: https://github.com/joshmn/scopa/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: 4.0.1
+specification_version: 4
+summary: Query objects for Rails. Encapsulate complex queries with validated parameters
+  and composable filters.
+test_files: []