sequel_count_comparisons 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b0dda31dca4ef83af94b35f825f9625af8dcb097804e73b5f616c3a2af3c99f2
+  data.tar.gz: 8120c91e4dce2d96d210372f15d559cae1945c1f0e09ed3c0f57b2f4dc0790ae
+SHA512:
+  metadata.gz: 05db3f4b5803e51c9e21453898178a57da956cb36b516870ad78c4f7cbba014d4c80dadc95a79bc5781fb8184de0ab605faa6d65f7a5f09d273f4a72f2701bd7
+  data.tar.gz: 25ea2ae4e012e05c5e9e1abf3993b41a9900c1f50c9b97d63d0f23bfc00a2e2369b1279b91cc6a1f4715798f4904c903c2562044bf0e4e3b990fd34b6926b6f3

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG

@@ -0,0 +1,3 @@
+=== 1.0.0 (2025-03-10)
+
+* Initial public release

data/README.md

@@ -0,0 +1,78 @@
+# Sequel::CountComparisons
+
+This gem adds five methods to `Sequel::Dataset`:
+
+* `#count_equals?`
+* `#count_greater_than?`
+* `#count_less_than?`
+* `#count_at_most?`
+* `#count_at_least?`
+
+These methods allow you to efficiently compare a dataset's row count to a given number.
+
+Why use this gem?
+
+* It generates efficient SQL queries to minimize database overhead, using
+`LIMIT`
+and `OFFSET` clauses to count only the rows needed. This is especially useful
+for large datasets.
+* It provides a readable API for expressing dataset count comparisons, which
+makes code easier to understand and less error-prone.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add sequel_count_comparisons
+
+If Bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install sequel_count_comparisons
+
+## Usage
+
+You can load this extension into specific datasets:
+
+```ruby
+ds = DB[:table].extension(:count_comparisons)
+``````
+
+Or you can load it into all of a database’s datasets:
+
+```ruby
+DB.extension(:count_comparisons)
+
+DB[:table].count_equals?(1)
+# SELECT EXISTS (SELECT 1 FROM table OFFSET 0) AND NOT EXISTS (SELECT 1 FROM table OFFSET 1)
+
+DB[:table].count_greater_than?(0)
+# SELECT 1 FROM table LIMIT 1
+
+DB[:table].count_greater_than?(1)
+# SELECT 1 FROM table LIMIT 1 OFFSET 1
+
+DB[:table].count_less_than?(1)
+# SELECT 1 FROM table LIMIT 1
+
+DB[:table].count_less_than?(5)
+# SELECT 1 FROM table LIMIT 1 OFFSET 4
+
+DB[:table].count_at_least?(3)
+# SELECT 1 FROM table LIMIT 1 OFFSET 2
+
+DB[:table].count_at_most?(100)
+# SELECT 1 FROM table LIMIT 1 OFFSET 100
+
+```
+
+## Caveats
+
+The gem is tested on PostgreSQL. It may or may not work for other databases.
+
+## License
+
+This library is released under the MIT License.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/eriklovmo/sequel_count_comparisons.

data/Rakefile

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

data/lib/sequel/count_comparisons/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Sequel
+  module CountComparisons
+    VERSION = '1.0.0'
+  end
+end

data/lib/sequel/extensions/count_comparisons.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'sequel'
+require_relative '../count_comparisons/version'
+
+# The count_comparisons extension adds the #count_greater_than?, #count_less_than?, #count_at_most?,
+# #count_at_least?, and #count_equals? methods to Dataset. These methods can be used to efficiently
+# compare a dataset's row count to a given number.
+
+# You can load this extension into specific datasets:
+#
+#   ds = DB[:table].extension(:count_comparisons)
+#
+# Or load it into all of a database's datasets:
+#
+#   DB.extension(:count_comparisons)
+
+module Sequel
+  module Extensions
+    module CountComparisons
+      LITERAL_1 = Sequel::SQL::AliasedExpression.new(1, :one)
+      private_constant :LITERAL_1
+
+      # Returns true if more than *number_of_rows* records exist in the dataset, false otherwise
+      #
+      # Equivalent to a "greater than" (>) comparison
+      #
+      # @param number_of_rows [Integer] The number to compare against
+      # @return [Boolean] Whether the dataset contains more rows than *number_of_rows*
+      # @raise [ArgumentError] If `number_of_rows` is not an integer
+      def count_greater_than?(number_of_rows)
+        unless number_of_rows.is_a?(Integer)
+          raise ArgumentError,
+                "`number_of_rows` must be an Integer, got #{number_of_rows.inspect}"
+        end
+
+        if number_of_rows.negative?
+          true
+        elsif number_of_rows.zero?
+          !empty?
+        else
+          ds = @opts[:sql] ? from_self : self
+          !ds.offset(number_of_rows).empty?
+        end
+      end
+
+      # Returns true if fewer than *number_of_rows* records exist in the dataset, false otherwise
+      #
+      # Equivalent to a "less than" (<) comparison
+      #
+      # @param number_of_rows [Integer] The number to compare against
+      # @return [Boolean] Whether the dataset contains fewer rows than *number_of_rows*
+      # @raise [ArgumentError] If `number_of_rows` is not an integer
+      def count_less_than?(number_of_rows)
+        unless number_of_rows.is_a?(Integer)
+          raise ArgumentError,
+                "`number_of_rows` must be an Integer, got #{number_of_rows.inspect}"
+        end
+
+        !count_greater_than?(number_of_rows - 1)
+      end
+
+      # Returns true if at least *number_of_rows* records exist in the dataset, false otherwise
+      #
+      # Equivalent to a "greater than or equal to" (>=) comparison
+      #
+      # @param number_of_rows [Integer] The number to compare against
+      # @return [Boolean] Whether the dataset contains at least *number_of_rows*
+      # @raise [ArgumentError] If `number_of_rows` is not an integer
+      def count_at_least?(number_of_rows)
+        unless number_of_rows.is_a?(Integer)
+          raise ArgumentError,
+                "`number_of_rows` must be an Integer, got #{number_of_rows.inspect}"
+        end
+
+        count_greater_than?(number_of_rows - 1)
+      end
+
+      # Returns true if at most *number_of_rows* records exist in the dataset, false otherwise
+      #
+      # Equivalent to a "less than or equal to" (<=) comparison
+      #
+      # @param number_of_rows [Integer] The number to compare against
+      # @return [Boolean] Whether the dataset contains at most *number_of_rows*
+      # @raise [ArgumentError] If `number_of_rows` is not an integer
+      def count_at_most?(number_of_rows)
+        !count_greater_than?(number_of_rows)
+      end
+
+      # Returns true if exactly *number_of_rows* records exist in the dataset, false otherwise
+      #
+      # Equivalent to an "equal to" (==) comparison
+      #
+      # @param number_of_rows [Integer] The number to compare against
+      # @return [Boolean] Whether the dataset contains exactly *number_of_rows*
+      # @raise [ArgumentError] If `number_of_rows` is not an integer
+      def count_equals?(number_of_rows)
+        unless number_of_rows.is_a?(Integer)
+          raise ArgumentError,
+                "`number_of_rows` must be an Integer, got #{number_of_rows.inspect}"
+        end
+
+        if number_of_rows.negative?
+          false
+        elsif number_of_rows.zero?
+          empty?
+        else
+          ds = @opts[:sql] ? from_self : self
+          ds = ds.unordered.select(LITERAL_1)
+          @db.get(
+            ds.offset(number_of_rows - 1).exists &
+            ~ds.offset(number_of_rows).exists
+          )
+        end
+      end
+    end
+  end
+
+  Sequel::Dataset.register_extension(:count_comparisons, Sequel::Extensions::CountComparisons)
+end

data/license.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Erik Lövmo
+
+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.

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: sequel_count_comparisons
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- eriklovmo
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-03-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG
+- README.md
+- Rakefile
+- lib/sequel/count_comparisons/version.rb
+- lib/sequel/extensions/count_comparisons.rb
+- license.txt
+homepage: https://github.com/eriklovmo/sequel_count_comparisons
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/eriklovmo/sequel_count_comparisons
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: 'Adds #count_equals?, #count_greater_than?, #count_less_than?, #count_at_least?
+  and #count_at_most? to Sequel::Dataset'
+test_files: []