miscellany 0.1.30 → 0.2.0

data/spec/miscellany/custom_preloaders_spec.rb

@@ -0,0 +1,63 @@
+require 'spec_helper'
+
+RSpec.describe Miscellany::CustomPreloaders do
+  describe Miscellany::CustomPreloaders::AssociationBuilderExtension do
+    it 'registers :preloader as a valid association option' do
+      expect(described_class.valid_options).to include(:preloader)
+    end
+  end
+
+  describe 'option registration on a real association' do
+    with_model :Author do
+      table { |t| t.string :name }
+      model do
+        has_many :books, preloader: 'SomePreloaderClass'
+      end
+    end
+
+    with_model :Book do
+      table { |t| t.integer :author_id }
+    end
+
+    it 'accepts the :preloader option without raising' do
+      # If AssociationBuilderExtension were not installed, ActiveRecord would
+      # reject the unknown :preloader option when the association is touched.
+      expect { Author.reflect_on_association(:books).options }.not_to raise_error
+      expect(Author.reflect_on_association(:books).options[:preloader])
+        .to eq 'SomePreloaderClass'
+    end
+  end
+
+  describe Miscellany::CustomPreloaders::PreloaderExtension do
+    # A minimal stand-in for ActiveRecord's Preloader whose default
+    # preloader_for returns :fallback, so we can observe override behavior.
+    let(:preloader) do
+      base = Class.new do
+        def preloader_for(_reflection, _owners)
+          :fallback
+        end
+      end
+      base.prepend(Miscellany::CustomPreloaders::PreloaderExtension)
+      base.new
+    end
+
+    def reflection_with(options)
+      double('reflection', options: options)
+    end
+
+    it 'falls back to the default when no custom preloader is configured' do
+      expect(preloader.preloader_for(reflection_with({}), [])).to eq :fallback
+    end
+
+    it 'returns a custom preloader class as-is' do
+      custom = Class.new
+      expect(preloader.preloader_for(reflection_with(preloader: custom), [])).to eq custom
+    end
+
+    it 'constantizes a string preloader name' do
+      stub_const('MyCustomPreloader', Class.new)
+      expect(preloader.preloader_for(reflection_with(preloader: 'MyCustomPreloader'), []))
+        .to eq MyCustomPreloader
+    end
+  end
+end

data/spec/miscellany/http_error_handling_spec.rb

@@ -0,0 +1,137 @@
+require 'spec_helper'
+require 'action_controller'
+
+RSpec.describe Miscellany::HttpErrorHandling do
+  # Captures what the concern hands to `render` instead of driving a real response.
+  controller_class = Class.new(ActionController::Base) do
+    include Miscellany::HttpErrorHandling
+
+    attr_reader :rendered
+
+    def render(**kwargs)
+      @rendered = kwargs
+    end
+  end
+
+  let(:controller) { controller_class.new }
+
+  def rendered_for(err, **kwargs)
+    controller.render_http_error(err, **kwargs)
+    controller.rendered
+  end
+
+  describe '#render_http_error' do
+    it 'renders an HttpError with its own status, message, and extra' do
+      err = Miscellany::HttpErrorHandling::HttpError.new('nope', status: 422, code: 'E_NOPE')
+      expect(rendered_for(err)).to eq(
+        json: { status: 422, message: 'nope', code: 'E_NOPE' },
+        status: 422,
+      )
+    end
+
+    it 'defaults to 400 when no status is available' do
+      expect(rendered_for(Miscellany::HttpErrorHandling::HttpError.new('nope'))[:status]).to eq 400
+    end
+
+    # Reached by `rescue_with_http_error`, which passes ordinary exceptions.
+    it 'renders a plain StandardError that carries no extra' do
+      expect(rendered_for(StandardError.new('boom'), status: 422)).to eq(
+        json: { status: 422, message: 'boom' },
+        status: 422,
+      )
+    end
+
+    # The idiom ParamValidator's docs recommend: field errors must reach the client
+    # as their own key, not folded into the message string.
+    it 'carries structured field errors through as extra' do
+      errors = { 'search_term' => ['must be at least 3 characters'] }
+      err = Miscellany::HttpErrorHandling::HttpError.new(
+        'invalid parameters', status: 422, parameter_errors: errors
+      )
+      expect(rendered_for(err)).to eq(
+        json: { status: 422, message: 'invalid parameters', parameter_errors: errors },
+        status: 422,
+      )
+    end
+
+    it 'prefers an explicit message over the exception message' do
+      expect(rendered_for(StandardError.new('boom'), message: 'friendlier')[:json][:message])
+        .to eq 'friendlier'
+    end
+  end
+
+  describe '.http_error' do
+    it 'resolves a Proc message against the exception' do
+      handler = controller_class.http_error(422, ->(err) { "custom: #{err.message}" })
+      controller.instance_exec(StandardError.new('boom'), &handler)
+      expect(controller.rendered).to eq(
+        json: { status: 422, message: 'custom: boom' },
+        status: 422,
+      )
+    end
+
+    it 'accepts the message as a block' do
+      handler = controller_class.http_error(422) { |err| "blocky: #{err.message}" }
+      controller.instance_exec(StandardError.new('boom'), &handler)
+      expect(controller.rendered[:json][:message]).to eq 'blocky: boom'
+    end
+
+    it 'lets an HttpError keep its own status rather than the handler default' do
+      handler = controller_class.http_error(500)
+      controller.instance_exec(Miscellany::HttpErrorHandling::HttpError.new('nope', status: 404), &handler)
+      expect(controller.rendered[:status]).to eq 404
+    end
+  end
+end
+
+RSpec.describe Miscellany::HttpErrorHandling::HttpError do
+  it 'defaults to a blank message, no status, and no extra' do
+    err = described_class.new
+    expect(err.message).to eq ''
+    expect(err.status).to be_nil
+    expect(err.extra).to eq({})
+  end
+
+  it 'treats a numeric positional argument as the status' do
+    err = described_class.new(404)
+    expect(err.status).to eq 404
+    expect(err.message).to eq ''
+  end
+
+  it 'treats a non-numeric positional argument as the message' do
+    err = described_class.new('boom')
+    expect(err.message).to eq 'boom'
+    expect(err.status).to be_nil
+  end
+
+  it 'accepts status and message as keywords' do
+    err = described_class.new(status: 422, message: 'bad input')
+    expect(err.status).to eq 422
+    expect(err.message).to eq 'bad input'
+  end
+
+  it 'combines a positional status with a keyword message' do
+    err = described_class.new(403, message: 'nope')
+    expect(err.status).to eq 403
+    expect(err.message).to eq 'nope'
+  end
+
+  it 'captures unknown keywords as extra' do
+    err = described_class.new('boom', code: 'E_BOOM', detail: 'context')
+    expect(err.extra).to eq(code: 'E_BOOM', detail: 'context')
+  end
+
+  it 'raises when status is given both positionally and as a keyword' do
+    expect { described_class.new(400, status: 500) }
+      .to raise_error(ArgumentError, /status supplied multiple times/)
+  end
+
+  it 'raises when message is given both positionally and as a keyword' do
+    expect { described_class.new('boom', message: 'also boom') }
+      .to raise_error(ArgumentError, /message supplied multiple times/)
+  end
+
+  it 'is a StandardError so it can be rescued' do
+    expect(described_class.new).to be_a(StandardError)
+  end
+end

data/spec/miscellany/jbuilder_partial_block_spec.rb

@@ -0,0 +1,41 @@
+require 'spec_helper'
+
+# JbuilderTemplateExt is meant to be prepended onto JbuilderTemplate. Rather than
+# stand up a full jbuilder render, we prepend it onto a stub that records what
+# partial! receives, which is exactly the behavior the extension changes.
+RSpec.describe Miscellany::Extensions::JBuilder::JbuilderTemplateExt do
+  let(:recorder_class) do
+    Class.new do
+      attr_reader :last_args, :last_kwargs
+
+      def partial!(*args, **kwargs)
+        @last_args = args
+        @last_kwargs = kwargs
+      end
+    end
+  end
+
+  let(:instance) do
+    klass = recorder_class
+    klass.prepend(described_class)
+    klass.new
+  end
+
+  it 'injects a given block as the :block keyword' do
+    blk = -> { :rendered }
+    instance.partial!('shared/thing', foo: 1, &blk)
+
+    expect(instance.last_kwargs[:block]).to eq blk
+    expect(instance.last_kwargs[:foo]).to eq 1
+  end
+
+  it 'does not add a :block keyword when no block is given' do
+    instance.partial!('shared/thing', foo: 1)
+    expect(instance.last_kwargs).not_to have_key(:block)
+  end
+
+  it 'passes positional arguments through unchanged' do
+    instance.partial!('shared/thing')
+    expect(instance.last_args).to eq ['shared/thing']
+  end
+end

data/spec/miscellany/json_uploads_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+# The process_action override needs a full controller/request stack to exercise.
+# The recursive parameter-merge logic, which is the substantive part, is unit
+# tested here in isolation.
+RSpec.describe Miscellany::JsonUploads do
+  let(:instance) { Class.new { include Miscellany::JsonUploads }.new }
+
+  # _merge_json_params logs a warning (via Rails.logger) when a value is supplied
+  # in both layers; stub Rails since the gem loads without it in the suite.
+  before { stub_const('Rails', double('Rails', logger: Logger.new(IO::NULL))) }
+
+  def merge(base, layer)
+    instance.send(:_merge_json_params, base, layer)
+  end
+
+  describe 'scalars' do
+    it 'prefers the layer value over the base' do
+      expect(merge('base', 'layer')).to eq 'layer'
+    end
+
+    it 'falls back to the base when the layer is blank' do
+      expect(merge('base', nil)).to eq 'base'
+      expect(merge('base', '')).to eq 'base'
+    end
+  end
+
+  describe 'hashes' do
+    it 'deep-merges, with the layer winning on overlapping leaves' do
+      expect(merge({ 'a' => 1, 'b' => 2 }, { 'b' => 3 })).to eq('a' => 1, 'b' => 3)
+    end
+
+    it 'keeps base-only keys when the layer omits them' do
+      expect(merge({ 'a' => 1 }, {})).to eq('a' => 1)
+    end
+
+    it 'merges nested hashes recursively' do
+      base = { 'outer' => { 'x' => 1, 'y' => 2 } }
+      layer = { 'outer' => { 'y' => 9 } }
+      expect(merge(base, layer)).to eq('outer' => { 'x' => 1, 'y' => 9 })
+    end
+  end
+
+  describe 'arrays' do
+    it 'merges element-wise against a parallel array layer' do
+      expect(merge([{ 'x' => 1 }, { 'x' => 2 }], [{ 'x' => 9 }, {}]))
+        .to eq([{ 'x' => 9 }, { 'x' => 2 }])
+    end
+
+    it 'merges element-wise against an index-keyed hash layer' do
+      expect(merge([10, 20], { '0' => 99 })).to eq([99, 20])
+    end
+  end
+end

data/spec/miscellany/local_lru_cache_spec.rb

@@ -0,0 +1,132 @@
+require 'spec_helper'
+
+RSpec.describe Miscellany::LocalLruCache do
+  subject(:cache) { described_class.new(3) }
+
+  describe '#[]= and #[]' do
+    it 'stores and retrieves values' do
+      cache[:a] = 1
+      expect(cache[:a]).to eq 1
+    end
+
+    it 'returns nil for missing keys' do
+      expect(cache[:missing]).to be_nil
+    end
+
+    it 'returns the assigned value from []=' do
+      expect(cache.send(:[]=, :a, 42)).to eq 42
+    end
+
+    it 'evicts the least-recently-used entry once over capacity' do
+      cache[:a] = 1
+      cache[:b] = 2
+      cache[:c] = 3
+      cache[:d] = 4 # pushes out :a, the oldest
+
+      expect(cache[:a]).to be_nil
+      expect(cache[:b]).to eq 2
+      expect(cache[:d]).to eq 4
+      expect(cache.count).to eq 3
+    end
+
+    it 'treats a read as a use, protecting the entry from eviction' do
+      cache[:a] = 1
+      cache[:b] = 2
+      cache[:c] = 3
+      cache[:a] # touch :a so :b becomes least-recently-used
+      cache[:d] = 4
+
+      expect(cache[:a]).to eq 1
+      expect(cache[:b]).to be_nil
+    end
+
+    it 'treats re-assignment as a use' do
+      cache[:a] = 1
+      cache[:b] = 2
+      cache[:c] = 3
+      cache[:a] = 10 # refresh recency of :a
+      cache[:d] = 4
+
+      expect(cache[:a]).to eq 10
+      expect(cache[:b]).to be_nil
+    end
+  end
+
+  describe '#fetch' do
+    it 'yields and stores on a miss' do
+      calls = 0
+      result = cache.fetch(:a) { calls += 1; 'computed' }
+      expect(result).to eq 'computed'
+      expect(calls).to eq 1
+    end
+
+    it 'does not yield on a hit' do
+      cache[:a] = 'stored'
+      calls = 0
+      result = cache.fetch(:a) { calls += 1; 'computed' }
+      expect(result).to eq 'stored'
+      expect(calls).to eq 0
+    end
+  end
+
+  describe '#delete' do
+    it 'removes an entry' do
+      cache[:a] = 1
+      expect(cache.delete(:a)).to eq 1
+      expect(cache[:a]).to be_nil
+    end
+  end
+
+  describe '#clear' do
+    it 'empties the cache' do
+      cache[:a] = 1
+      cache[:b] = 2
+      cache.clear
+      expect(cache.count).to eq 0
+    end
+  end
+
+  describe '#to_a and #each' do
+    it 'orders entries most-recently-used first' do
+      cache[:a] = 1
+      cache[:b] = 2
+      expect(cache.to_a).to eq [[:b, 2], [:a, 1]]
+    end
+
+    it 'iterates most-recently-used first' do
+      cache[:a] = 1
+      cache[:b] = 2
+      seen = []
+      cache.each { |pair| seen << pair }
+      expect(seen).to eq [[:b, 2], [:a, 1]]
+    end
+  end
+
+  describe '#max_size=' do
+    it 'rejects a size below one' do
+      expect { cache.max_size = 0 }.to raise_error(ArgumentError)
+    end
+
+    it 'evicts down to the new size, dropping the oldest entries' do
+      cache[:a] = 1
+      cache[:b] = 2
+      cache[:c] = 3
+      cache.max_size = 1
+
+      expect(cache.count).to eq 1
+      expect(cache[:c]).to eq 3 # newest survives
+      expect(cache[:a]).to be_nil
+    end
+
+    it 'keeps every entry when only shrinking by one' do
+      cache[:a] = 1
+      cache[:b] = 2
+      cache[:c] = 3
+      cache.max_size = 2
+
+      expect(cache.count).to eq 2
+      expect(cache[:b]).to eq 2
+      expect(cache[:c]).to eq 3
+    end
+  end
+end

data/spec/miscellany/param_validator_spec.rb

@@ -113,6 +113,82 @@ describe Miscellany::ParamValidator do
       end
     end
 
+    describe 'an unsupported type' do
+      # A type with no coercion rule is a mistake in the validator definition,
+      # not bad user input, so it must fail loudly instead of silently nulling.
+      it 'raises, naming the type and the key' do
+        expect do
+          Miscellany::ParamValidator.check({ value: 'x' }) { p :value, type: Symbol }
+        end.to raise_error(Miscellany::ParamValidator::UnsupportedTypeError, /Symbol.*:value/)
+      end
+
+      it 'leaves the value untouched' do
+        params = { value: 'x' }
+        begin
+          Miscellany::ParamValidator.check(params) { p :value, type: Symbol }
+        rescue Miscellany::ParamValidator::UnsupportedTypeError
+          # asserted separately above
+        end
+        expect(params[:value]).to eq 'x'
+      end
+
+      it 'accepts a value that is already an instance of that type' do
+        expect_coercion(:already_a_symbol, Symbol, :already_a_symbol)
+      end
+    end
+
+    describe 'given positionally' do
+      def assert_positional(raw, expectation, &blk)
+        result = Miscellany::ParamValidator.assert({ value: raw }, handle: ->(_v) { raise 'Invalid' }, &blk)
+        expect(result[:value]).to eq expectation
+      end
+
+      it 'coerces just as the keyword form does' do
+        assert_positional('5', 5) { p :value, Integer }
+      end
+
+      it 'accepts a list of types' do
+        assert_positional('5', 5) { p :value, [Integer, String] }
+      end
+
+      it 'combines with flags in any order' do
+        assert_positional('5', 5) { p :value, :present, Integer }
+        assert_positional('5', 5) { p :value, Integer, :present }
+      end
+
+      it 'still rejects genuinely unrecognized arguments' do
+        expect do
+          Miscellany::ParamValidator.check({ value: '5' }) { p :value, Integer, String }
+        end.to raise_error(ArgumentError, /positional/)
+      end
+    end
+
+    describe 'BigDecimal' do
+      it 'coerces a decimal string' do
+        expect_coercion('12.34', BigDecimal, BigDecimal('12.34'))
+      end
+
+      it 'strips currency formatting' do
+        expect_coercion('$1,234.56', BigDecimal, BigDecimal('1234.56'))
+      end
+
+      # Routing through Float would silently truncate here, which defeats the
+      # point of asking for a BigDecimal.
+      it 'keeps digits beyond what a Float can hold' do
+        expect_coercion('1.234567890123456789', BigDecimal, BigDecimal('1.234567890123456789'))
+      end
+
+      it 'coerces a numeric value' do
+        expect_coercion(5, BigDecimal, BigDecimal(5))
+      end
+
+      it 'reports a validation error for a non-numeric string' do
+        expect_invalid do
+          p :some_string, type: BigDecimal
+        end
+      end
+    end
+
     describe ':bool' do
       it 'transforms booleans' do
         expect_coercion('t', :bool, true)
@@ -172,6 +248,27 @@ describe Miscellany::ParamValidator do
         p :some_string, pattern: /^Steve$/
       end
     end
+
+    # A matching pattern must not short-circuit the rest of the parameter.
+    it 'still applies the other checks when the pattern matches' do
+      expect_invalid do
+        p :some_string, pattern: /^Rob/, in: %w[Steve]
+      end
+    end
+
+    it 'reports the failing key when an earlier key matched' do
+      result = Miscellany::ParamValidator.check({ matches: 'Robert', fails: 'Steve' }) do
+        p %i[matches fails], pattern: /^Rob/
+      end
+      expect(result.serialize).to eq('fails' => ['must match pattern: /^Rob/'])
+    end
+
+    it 'does not discard errors collected for earlier keys' do
+      result = Miscellany::ParamValidator.check({ fails: 'Steve', matches: 'Robert' }) do
+        p %i[fails matches], pattern: /^Rob/
+      end
+      expect(result.serialize).to eq('fails' => ['must match pattern: /^Rob/'])
+    end
   end
 
   describe 'items:' do

data/spec/miscellany/require_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+require 'open3'
+
+# These run in a fresh process on purpose: by the time the rest of the suite
+# loads, ActiveRecord is already in memory, which is exactly what masks a missing
+# require in lib/miscellany.rb.
+RSpec.describe 'requiring miscellany' do
+  LIB_PATH = File.expand_path('../../lib', __dir__)
+
+  # stdout and stderr are kept apart deliberately: Ruby writes unrelated
+  # deprecation warnings to stderr, which would otherwise corrupt the result.
+  def ruby(source)
+    out, err, status = Open3.capture3(
+      Gem.ruby, '-rbundler/setup', "-I#{LIB_PATH}", '-e', source
+    )
+    raise "subprocess exited #{status.exitstatus}:\n#{err}" unless status.success?
+
+    out
+  end
+
+  it 'succeeds without ActiveRecord having been loaded first' do
+    expect(ruby('require "miscellany"; print "OK"')).to eq 'OK'
+  end
+
+  it 'installs the ActiveRecord extensions' do
+    expect(ruby('require "miscellany"; print ActiveRecord::Base.respond_to?(:prefetch)')).to eq 'true'
+    expect(ruby('require "miscellany"; print ActiveRecord::Base.respond_to?(:with_computed)')).to eq 'true'
+  end
+
+  it 'exposes the plain-Ruby helpers' do
+    expect(ruby('require "miscellany"; print Miscellany::LocalLruCache.new(2)[:missing].inspect')).to eq 'nil'
+    expect(ruby('require "miscellany"; print Miscellany::ParamValidator.check({}) { }.serialize.inspect')).to eq 'nil'
+  end
+end

data/spec/miscellany/sliced_response_spec.rb

@@ -109,10 +109,10 @@ describe Miscellany::SlicedResponse do
       include_examples "sortable"
 
       it "uses the ComplexQuery sort_parser if valid_sorts is not given" do
-        r = subject.sliced_json(source, { **slice_params, sort: "created_at" }, {})
+        r = subject.sliced_json(source, { **slice_params, sort: "created_at" })
         expect(r[:sort]).to eql nil
 
-        r = subject.sliced_json(source, { **slice_params, sort: "title" }, {})
+        r = subject.sliced_json(source, { **slice_params, sort: "title" })
         expect(r[:sort]).to eql "title ASC"
       end
 
@@ -122,6 +122,35 @@ describe Miscellany::SlicedResponse do
       end
     end
 
+    context "with out-of-range paging" do
+      let(:source) { ARModel.all }
+
+      # A page_size of 0 used to divide by zero while computing page_count.
+      it "rejects a page_size below 1" do
+        [0, -5].each do |bad|
+          expect do
+            subject.sliced_json(source, { page_size: bad }, **slice_config)
+          end.to raise_error(Miscellany::HttpErrorHandling::HttpError, /page_size must be at least 1/)
+        end
+      end
+
+      # A page below 1 used to reach SQL as a negative OFFSET. ComplexQuery#page
+      # already clamps, so the slice does too.
+      it "clamps a page below 1 to the first page" do
+        [0, -1].each do |bad|
+          r = subject.sliced_json(source, { page: bad }, **slice_config)
+          expect(r[:page]).to eql 1
+          expect(r[:slice_start]).to eql 0
+          expect_items(r, ARModel.all.limit(3))
+        end
+      end
+
+      it "still reports page_count for a valid page_size" do
+        r = subject.sliced_json(source, { page_size: 4 }, **slice_config)
+        expect(r[:page_count]).to eql 3
+      end
+    end
+
     it "enforces allow_all" do
       expect do
         subject.sliced_json(ARModel.all, { page: "all" }, **slice_config)

data/spec/miscellany/sort_lang_spec.rb

@@ -122,6 +122,39 @@ describe Miscellany::SortLang do
           {:column=>"created_at", :force_order=>false, :key=>"created_at"},
         ]
       end
+
+      # SlicedResponse surfaces these straight to API clients, so the message has
+      # to read as a sentence rather than a stringified Hash.
+      context "with ignore_errors: false" do
+        it "raises naming the unparseable sort" do
+          expect { subject.parse("not a sort!", ignore_errors: false) }
+            .to raise_error(Miscellany::SortLang::Parser::SortParsingError, /could not parse.*"not a sort!"/i)
+        end
+
+        it "raises naming the unknown column" do
+          expect { subject.parse("updated_at", ignore_errors: false) }
+            .to raise_error(Miscellany::SortLang::Parser::SortParsingError, /unknown sort column.*"updated_at"/i)
+        end
+
+        it "does not raise for a valid sort" do
+          expect { subject.parse("title DESC", ignore_errors: false) }.not_to raise_error
+        end
+      end
+    end
+
+    describe "#valid?" do
+      it "is true for a known column" do
+        expect(subject.valid?("title")).to be true
+        expect(subject.valid?("created_at DESC")).to be true
+      end
+
+      it "is false for an unknown column" do
+        expect(subject.valid?("updated_at")).to be false
+      end
+
+      it "is false for an unparseable sort" do
+        expect(subject.valid?("not a sort!")).to be false
+      end
     end
   end
 end