miscellany 0.1.30 → 0.2.0

data/spec/miscellany/batch_matcher_spec.rb

@@ -0,0 +1,130 @@
+require 'spec_helper'
+
+RSpec.describe Miscellany::BatchMatcher do
+  describe 'simple (single-model) matching' do
+    with_model :Rule do
+      table do |t|
+        t.string :import_id
+        t.string :label
+      end
+    end
+
+    let!(:rule_a) { Rule.create!(import_id: 'IMP-A', label: 'Alpha') }
+    let!(:rule_b) { Rule.create!(import_id: 'IMP-B', label: 'Beta') }
+
+    # [csv_key, db_key, human_name]; first entry is the primary column.
+    let(:columns) { [[:rule_id, :id, 'ID'], [:rule_import_id, :import_id, 'Import ID']] }
+    let(:rows) do
+      [
+        { rule_id: rule_a.id, rule_import_id: 'IMP-A' },
+        { rule_id: rule_b.id, rule_import_id: 'IMP-B' },
+      ]
+    end
+
+    def matcher(opts = {})
+      described_class.new(Rule, rows, **{ columns: columns }.merge(opts))
+    end
+
+    describe '#get_for_row!' do
+      it 'matches on the primary column' do
+        expect(matcher.get_for_row!(rule_id: rule_a.id)).to eq rule_a
+      end
+
+      it 'matches on a secondary column' do
+        expect(matcher.get_for_row!(rule_import_id: 'IMP-B')).to eq rule_b
+      end
+
+      it 'matches when consistent values are given for multiple columns' do
+        expect(matcher.get_for_row!(rule_id: rule_a.id, rule_import_id: 'IMP-A')).to eq rule_a
+      end
+
+      it 'raises RecordNotFound when nothing matches' do
+        expect { matcher.get_for_row!(rule_import_id: 'NOPE') }
+          .to raise_error(ActiveRecord::RecordNotFound, /Import ID/)
+      end
+    end
+
+    describe '#get_for_row' do
+      it 'returns nil instead of raising when nothing matches' do
+        expect(matcher.get_for_row(rule_import_id: 'NOPE')).to be_nil
+      end
+
+      it 'returns the record when it matches' do
+        expect(matcher.get_for_row(rule_id: rule_b.id)).to eq rule_b
+      end
+    end
+
+    describe '#get_primary_for_row!' do
+      it 'returns the primary key value for a primary-column row' do
+        expect(matcher.get_primary_for_row!(rule_id: rule_a.id)).to eq rule_a.id.to_s
+      end
+
+      it 'resolves the primary key value from a secondary column' do
+        expect(matcher.get_primary_for_row!(rule_import_id: 'IMP-B')).to eq rule_b.id.to_s
+      end
+    end
+
+    describe '#should_match?' do
+      it 'is true when any configured column has a value' do
+        expect(matcher.should_match?(rule_import_id: 'IMP-A')).to be true
+      end
+
+      it 'is false when no configured column has a value' do
+        expect(matcher.should_match?(unrelated: 'x')).to be false
+        expect(matcher.should_match?({})).to be false
+      end
+    end
+
+    describe 'validate_all' do
+      let(:conflicting_row) { { rule_id: rule_a.id, rule_import_id: 'IMP-B' } }
+
+      it 'raises when columns resolve to different records (default)' do
+        expect { matcher.get_for_row!(conflicting_row) }
+          .to raise_error(ActiveRecord::RecordNotFound, /resolved to different objects/)
+      end
+
+      it 'returns the first match when validation is disabled' do
+        expect(matcher(validate_all: false).get_for_row!(conflicting_row)).to eq rule_a
+      end
+    end
+  end
+
+  describe 'polymorphic matching' do
+    with_model :Account do
+      table { |t| t.integer :canvas_id }
+    end
+
+    with_model :Course do
+      table { |t| t.integer :canvas_id }
+    end
+
+    let!(:account) { Account.create!(canvas_id: 100) }
+    let!(:course) { Course.create!(canvas_id: 200) }
+
+    let(:columns) { [[:canvas_context_id, :canvas_id, 'Canvas ID']] }
+    let(:rows) do
+      [
+        { context_type: 'Account', canvas_context_id: 100 },
+        { context_type: 'Course', canvas_context_id: 200 },
+      ]
+    end
+
+    def matcher
+      described_class.new(
+        [Account, Course], rows,
+        polymorphic_on: :context_type,
+        columns: columns,
+      )
+    end
+
+    it 'resolves rows to the correct model based on the polymorphic type' do
+      expect(matcher.get_for_row!(rows[0])).to eq account
+      expect(matcher.get_for_row!(rows[1])).to eq course
+    end
+
+    it 'raises for an unknown polymorphic type' do
+      expect { matcher.get_for_row!(context_type: 'Widget', canvas_context_id: 1) }
+        .to raise_error(ActiveRecord::RecordNotFound)
+    end
+  end
+end

data/spec/miscellany/batch_processor_spec.rb

@@ -0,0 +1,75 @@
+require 'spec_helper'
+
+RSpec.describe Miscellany::BatchProcessor do
+  it 'processes a batch as soon as it reaches the batch size' do
+    batches = []
+    processor = described_class.new(of: 2) { |batch| batches << batch.dup }
+
+    processor << 1
+    expect(batches).to be_empty # not yet full
+
+    processor << 2
+    expect(batches).to eq [[1, 2]] # flushed at size 2
+
+    processor << 3
+    expect(batches).to eq [[1, 2]] # partial batch held back
+  end
+
+  describe '#flush' do
+    it 'processes the remaining partial batch' do
+      batches = []
+      processor = described_class.new(of: 5) { |batch| batches << batch.dup }
+
+      processor << 1
+      processor << 2
+      processor.flush
+
+      expect(batches).to eq [[1, 2]]
+    end
+
+    it 'does nothing when there is nothing buffered' do
+      calls = 0
+      processor = described_class.new(of: 5) { |_batch| calls += 1 }
+      processor.flush
+      expect(calls).to eq 0
+    end
+
+    it 'does not re-run on a second flush' do
+      batches = []
+      processor = described_class.new(of: 5) { |batch| batches << batch.dup }
+      processor << 1
+      processor.flush
+      processor.flush
+      expect(batches).to eq [[1]]
+    end
+  end
+
+  describe '#add_all' do
+    it 'enqueues each item, flushing full batches along the way' do
+      batches = []
+      processor = described_class.new(of: 2) { |batch| batches << batch.dup }
+      processor.add_all([1, 2, 3, 4, 5])
+      expect(batches).to eq [[1, 2], [3, 4]]
+      processor.flush
+      expect(batches).to eq [[1, 2], [3, 4], [5]]
+    end
+  end
+
+  describe 'ensure_once' do
+    it 'invokes the block once on flush even with no items' do
+      batches = []
+      processor = described_class.new(of: 5, ensure_once: true) { |batch| batches << batch.dup }
+      processor.flush
+      expect(batches).to eq [[]]
+    end
+
+    it 'does not invoke the block an extra time when items were already processed' do
+      batches = []
+      processor = described_class.new(of: 2, ensure_once: true) { |batch| batches << batch.dup }
+      processor << 1
+      processor << 2 # full batch flushes here
+      processor.flush # nothing buffered, already flushed once
+      expect(batches).to eq [[1, 2]]
+    end
+  end
+end

data/spec/miscellany/batched_destruction_spec.rb

@@ -0,0 +1,66 @@
+require 'spec_helper'
+
+RSpec.describe Miscellany::BatchedDestruction do
+  with_model :Widget do
+    table do |t|
+      t.string :name
+      t.boolean :archived, default: false
+    end
+
+    model do
+      include Miscellany::BatchedDestruction
+    end
+  end
+
+  before do
+    5.times { |i| Widget.create!(name: "w#{i}") }
+  end
+
+  describe '.bulk_destroy' do
+    it 'deletes every matching record' do
+      expect { Widget.bulk_destroy }.to change(Widget, :count).from(5).to(0)
+    end
+
+    it 'works against a scoped relation, deleting only the scope' do
+      Widget.where(name: 'w0').update_all(archived: true)
+      expect { Widget.where(archived: true).bulk_destroy }
+        .to change(Widget, :count).from(5).to(4)
+    end
+
+    it 'runs the bulk_destroy callbacks around the deletion' do
+      ran = []
+      Widget.set_callback(:bulk_destroy, :before) { ran << :before }
+      Widget.set_callback(:bulk_destroy, :after) { ran << :after }
+
+      Widget.bulk_destroy
+      expect(ran).to eq [:before, :after]
+    end
+
+    it 'runs the per-batch callbacks' do
+      seen_batches = 0
+      Widget.set_callback(:destroy_batch, :before) { seen_batches += 1 }
+
+      Widget.bulk_destroy
+      expect(seen_batches).to be >= 1
+    end
+  end
+
+  describe '.destroy_bulk_batch override (soft deletion)' do
+    it 'lets a model swap hard deletion for a custom strategy' do
+      def Widget.destroy_bulk_batch(batch, _options)
+        where(id: batch.map(&:id)).update_all(archived: true)
+      end
+
+      expect { Widget.bulk_destroy }.not_to change(Widget, :count)
+      expect(Widget.where(archived: false)).to be_empty
+    end
+  end
+
+  describe '#destroy' do
+    it 'routes a single record through the bulk path by default' do
+      widget = Widget.first
+      expect { widget.destroy }.to change(Widget, :count).from(5).to(4)
+      expect(Widget.exists?(widget.id)).to be false
+    end
+  end
+end

data/spec/miscellany/batching_csv_processor_spec.rb

@@ -0,0 +1,138 @@
+require 'spec_helper'
+
+RSpec.describe Miscellany::BatchingCsvProcessor do
+  with_model :Widget do
+    table do |t|
+      t.string :name
+      t.string :size
+    end
+  end
+
+  # Concrete processor wiring the abstract hooks to a real model.
+  let(:processor_class) do
+    klass = Class.new(described_class) do
+      attr_reader :logged_errors
+
+      def initialize(*)
+        super
+        @logged_errors = []
+      end
+
+      def get_row_errors(row)
+        row[:name].blank? ? ['name is required'] : []
+      end
+
+      def log_line_error(message, line_number, **_kwargs)
+        @logged_errors << [line_number, message]
+      end
+
+      def find_or_init(row)
+        Widget.find_or_initialize_by(name: row[:name])
+      end
+
+      def apply_row_to_model(row, instance)
+        raise Miscellany::BatchingCsvProcessor::RowError, 'bad size' if row[:size] == 'bad'
+
+        instance.size = row[:size]
+      end
+    end
+    klass.const_set(:HEADERS, %i[name size])
+    klass
+  end
+
+  let(:csv) { "name,size\nwidget_a,small\nwidget_b,large\n" }
+
+  def processor(data = csv)
+    processor_class.new(data)
+  end
+
+  describe '#process_in_batches' do
+    it 'yields the validated rows, tagged with line numbers' do
+      seen = []
+      processor.process_in_batches { |batch| seen.concat(batch) }
+
+      expect(seen.map { |r| r[:name] }).to eq %w[widget_a widget_b]
+      expect(seen.map { |r| r[:line_number] }).to eq [1, 2]
+    end
+
+    it 'skips invalid rows and logs an error for each' do
+      proc = processor("name,size\n,small\nwidget_b,large\n")
+      seen = []
+      proc.process_in_batches { |batch| seen.concat(batch) }
+
+      expect(seen.map { |r| r[:name] }).to eq %w[widget_b]
+      expect(proc.logged_errors).to eq [[1, 'name is required']]
+    end
+  end
+
+  describe '#build_model_from_row' do
+    it 'returns a populated, changed model for a valid row' do
+      model = processor.build_model_from_row(name: 'widget_a', size: 'small', line_number: 1)
+      expect(model).to be_a(Widget)
+      expect(model.size).to eq 'small'
+      expect(model).to be_changed
+    end
+
+    it 'logs and swallows a RowError, returning nil' do
+      proc = processor
+      result = proc.build_model_from_row(name: 'widget_a', size: 'bad', line_number: 4)
+      expect(result).to be_nil
+      expect(proc.logged_errors).to eq [[4, 'bad size']]
+    end
+  end
+
+  describe '#batch_rows_to_models' do
+    it 'returns the changed models built from the rows' do
+      rows = [
+        { name: 'widget_a', size: 'small', line_number: 1 },
+        { name: 'widget_b', size: 'large', line_number: 2 },
+      ]
+      models = processor.batch_rows_to_models(rows)
+      expect(models.map(&:name)).to eq %w[widget_a widget_b]
+    end
+  end
+
+  describe '#map_defined_columns' do
+    it 'remaps only the keys present in the row' do
+      row = { old_name: 'a', old_size: 'b' }
+      mapped = processor.map_defined_columns(row, name: :old_name, size: :old_size, missing: :nope)
+      expect(mapped).to eq(name: 'a', size: 'b')
+    end
+  end
+
+  describe '.headers_match?' do
+    it 'is true when every required header is present' do
+      expect(processor_class.headers_match?(%i[name size extra])).to be true
+    end
+
+    it 'is false when a required header is missing' do
+      expect(processor_class.headers_match?(%i[name])).to be false
+    end
+  end
+
+  describe '.file_matches?' do
+    # file_matches? parses the raw header line into strings, so a class using
+    # string HEADERS is what the method is designed to compare against.
+    let(:string_header_class) do
+      klass = Class.new(described_class)
+      klass.const_set(:HEADERS, %w[name size])
+      klass
+    end
+
+    it 'is true when the header line contains the required columns' do
+      file = StringIO.new("name,size\nwidget_a,small\n")
+      expect(string_header_class.file_matches?(file)).to be true
+    end
+
+    it 'is false when a required column is missing' do
+      file = StringIO.new("name\nwidget_a\n")
+      expect(string_header_class.file_matches?(file)).to be false
+    end
+
+    it 'rewinds the file so it can be read again afterward' do
+      file = StringIO.new("name,size\nwidget_a,small\n")
+      string_header_class.file_matches?(file)
+      expect(file.readline).to eq "name,size\n"
+    end
+  end
+end

data/spec/miscellany/complex_query_spec.rb

@@ -0,0 +1,220 @@
+require 'spec_helper'
+
+# Concrete subclass exercising the abstract ComplexQuery template. A named
+# (non-anonymous) class is required: #in_batches derives a temp-table name from
+# self.class.name, and #valid_sorts reads self.class::SORTABLE_COLUMNS.
+class WidgetReportQuery < Miscellany::ComplexQuery
+  SORTABLE_COLUMNS = { 'name' => 'name' }.freeze
+
+  def build_query
+    "SELECT id, name FROM #{options[:table]}"
+  end
+
+  def build_count_query
+    "SELECT COUNT(*) AS count FROM #{options[:table]}"
+  end
+
+  # Subclasses are how the protected filter helpers are actually reached, so the
+  # specs exercise them the same way.
+  def date_filter_for(*args, **kwargs)
+    date_filter(*args, **kwargs)
+  end
+
+  def sanitize_sql_for(*args)
+    sanitize_sql(*args)
+  end
+end
+
+RSpec.describe Miscellany::ComplexQuery do
+  with_model :Widget do
+    table { |t| t.string :name }
+  end
+
+  let(:table) { Widget.table_name }
+
+  before do
+    %w[apple banana cherry].each { |n| Widget.create!(name: n) }
+  end
+
+  def query(opts = {})
+    WidgetReportQuery.new({ table: table }.merge(opts))
+  end
+
+  describe '#count' do
+    it 'returns the scalar count from build_count_query' do
+      expect(query.count).to eq 3
+    end
+  end
+
+  describe '#page' do
+    it 'returns a page of records with pagination metadata' do
+      result = query(sort: 'name').page(1, page_size: 2)
+
+      expect(result[:page]).to eq 1
+      expect(result[:total_count]).to eq 3
+      expect(result[:page_count]).to eq 2 # ceil(3 / 2)
+      expect(result[:page_size]).to eq 2
+      expect(result[:records].map { |r| r['name'] }).to eq %w[apple banana]
+    end
+
+    it 'returns the second page' do
+      result = query(sort: 'name').page(2, page_size: 2)
+      expect(result[:records].map { |r| r['name'] }).to eq %w[cherry]
+    end
+
+    it 'clamps a page below one up to one' do
+      expect(query.page(0, page_size: 2)[:page]).to eq 1
+    end
+
+    it 'floors a page size below two to ten' do
+      expect(query.page(1, page_size: 1)[:page_size]).to eq 10
+    end
+
+    it 'reports the sort string when sorting' do
+      expect(query(sort: 'name').page(1)[:sort]).to include('name')
+    end
+  end
+
+  describe '#slice' do
+    it 'returns records at the given offset and length, honoring raw_sort' do
+      records = query.slice(1, 1, raw_sort: 'name ASC')
+      expect(records.map { |r| r[:name] }).to eq %w[banana]
+    end
+
+    it 'exposes records with indifferent access' do
+      record = query.slice(0, 1, raw_sort: 'name ASC').first
+      expect(record[:name]).to eq 'apple'
+      expect(record['name']).to eq 'apple'
+    end
+  end
+
+  describe '#sql' do
+    it 'appends ORDER BY when a sort is configured' do
+      expect(query(sort: 'name').sql).to match(/ORDER BY/i)
+    end
+
+    it 'omits ORDER BY when no sort is configured' do
+      expect(query.sql).not_to match(/ORDER BY/i)
+    end
+  end
+
+  describe '#in_batches' do
+    it 'yields every record across batches and cleans up the temp table' do
+      seen = []
+      query.in_batches(of: 2) { |batch| seen.concat(batch.map { |r| r[:name] }) }
+      expect(seen.sort).to eq %w[apple banana cherry]
+    end
+
+    it 'can be run repeatedly (temp table is dropped each time)' do
+      expect { 2.times { query.in_batches(of: 2) { |_b| } } }.not_to raise_error
+    end
+
+    # Rails' in_batches never hands the block an empty batch; neither should this.
+    it 'does not yield a trailing empty batch' do
+      sizes = []
+      query.in_batches(of: 2) { |batch| sizes << batch.size }
+      expect(sizes).to eq [2, 1]
+    end
+
+    it 'does not yield at all when there are no records' do
+      Widget.delete_all
+      sizes = []
+      query.in_batches(of: 2) { |batch| sizes << batch.size }
+      expect(sizes).to eq []
+    end
+  end
+
+  describe '#find_each' do
+    it 'yields each record as a hash' do
+      names = []
+      query.find_each(batch_size: 2) { |r| names << r[:name] }
+      expect(names.sort).to eq %w[apple banana cherry]
+    end
+  end
+
+  describe '#valid_sort?' do
+    it 'returns false for a blank sort' do
+      expect(query.valid_sort?(nil)).to be false
+      expect(query.valid_sort?('')).to be false
+    end
+
+    it 'returns true for a sort over a sortable column' do
+      expect(query.valid_sort?('name')).to be true
+    end
+
+    it 'returns false for a sort over an unknown column' do
+      expect(query.valid_sort?('not_a_column')).to be false
+    end
+  end
+
+  describe '#join_filters (protected helper)' do
+    subject(:q) { query }
+
+    it 'ANDs present clauses together, wrapping each in parentheses' do
+      expect(q.send(:join_filters, 'a = 1', 'b = 2')).to eq '(a = 1) AND (b = 2)'
+    end
+
+    it 'drops blank clauses' do
+      expect(q.send(:join_filters, 'a = 1', nil, '', false)).to eq '(a = 1)'
+    end
+
+    it 'falls back to 1=1 when nothing is present' do
+      expect(q.send(:join_filters, nil, false)).to eq '1=1'
+    end
+  end
+
+  describe '#date_filter' do
+    let(:dated) { query(filters: { 'created_start' => '2024-01-01', 'created_end' => '2024-01-31' }) }
+
+    # The Symbol/String shorthand looks the range up in `filters` by prefix.
+    it 'resolves a Symbol key against filters' do
+      expect(dated.date_filter_for('created_at', :created))
+        .to match(/created_at BETWEEN '2024-01-01T00:00:00.*' AND '2024-01-31T23:59:59/)
+    end
+
+    it 'resolves a String key against filters' do
+      expect(dated.date_filter_for('created_at', 'created'))
+        .to match(/created_at BETWEEN '2024-01-01T00:00:00.*' AND '2024-01-31T23:59:59/)
+    end
+
+    it 'accepts an explicit range, expanding it to whole days' do
+      expect(query.date_filter_for('created_at', ['2024-01-01', '2024-01-31']))
+        .to match(/created_at BETWEEN '2024-01-01T00:00:00.*' AND '2024-01-31T23:59:59/)
+    end
+
+    it 'builds a one-sided clause when the filter only has a start' do
+      q = query(filters: { 'created_start' => '2024-01-01' })
+      expect(q.date_filter_for('created_at', :created)).to match(/created_at >= '2024-01-01T00:00:00/)
+    end
+  end
+
+  describe '#sanitize_sql' do
+    it 'quotes a bind value' do
+      expect(query.sanitize_sql_for('name = ?', "O'Brien")).to eq %(name = 'O''Brien')
+    end
+
+    it 'expands an IN list' do
+      expect(query.sanitize_sql_for('name IN (?)', %w[apple banana]))
+        .to eq "name IN ('apple','banana')"
+    end
+  end
+
+  describe '#datetime_filter (protected helper)' do
+    subject(:q) { query }
+
+    it 'builds a BETWEEN clause when both bounds are present' do
+      sql = q.send(:datetime_filter, 'created_at', ['2024-01-01', '2024-01-31'])
+      expect(sql).to match(/created_at BETWEEN '2024-01-01.*' AND '2024-01-31/)
+    end
+
+    it 'builds a lower-bound clause when only the start is present' do
+      sql = q.send(:datetime_filter, 'created_at', ['2024-01-01', nil])
+      expect(sql).to match(/created_at >= '2024-01-01/)
+    end
+
+    it 'builds an upper-bound clause when only the end is present' do
+      sql = q.send(:datetime_filter, 'created_at', [nil, '2024-01-31'])
+      expect(sql).to match(/created_at <= '2024-01-31/)
+    end
+  end
+end

data/spec/miscellany/computed_columns_spec.rb

@@ -49,7 +49,8 @@ describe Miscellany::ComputedColumns do
   end
 
   it 'generally works' do
-    ActiveRecord::Base.verbose_query_logs = true
+    # Debug aid only; removed from ActiveRecord in Rails 7.1.
+    ActiveRecord::Base.verbose_query_logs = true if ActiveRecord::Base.respond_to?(:verbose_query_logs=)
     posts = Post.with_computed(:favorite_comments_count)
     expect(posts.except(:select).count).to eq 3
     expect(posts[0].favorite_comments_count).to eq 1