bitwise_attributes 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d64d7b8f1ab83f3c86a41ae0a2c868f5d5f49599172e597e789484d7bb36834
-  data.tar.gz: c57864b2eb6228a95cc7ef390eb1054851682a2af0b3921eaf4cfaa0946b7d59
+  metadata.gz: 838a31f15821813cb22ce30c7830c6b0d7d77f106346a0902fe7e2dc97d40ed0
+  data.tar.gz: 1e2c6222ab5c571dbccdde150eba4587b60c70da76ebecc4dd111e0e2457224d
 SHA512:
-  metadata.gz: 411acc6c6b0a0041191c603d213fe563d1c444e3921df4890c21016acc571b1c044ea6a898105f5eca0200551fdb2b3cc6fa7dcaf94a875e2a955a5dfdbf963a
-  data.tar.gz: 715f9fba193a68687e85a0bdf1f52df8f6260972ed9bb6353298c75ff5a24011e0f87a100b3addc262775e264b6ef6521273569982fd4c40a9b6c6a1464df92b
+  metadata.gz: d360c4318ebca0adc53dd75a9081670f0362171a98385c79e5eaf221056d7074d75009a11022aaea1e5a1bf0e6ed7f4cfc962ef4db0bdeabcce672c4b5cf01a9
+  data.tar.gz: d3410f2652d74877c51b97c12cffeaff314de1abcba061f0d0c9644f88953bc6328e045b84a271057d8c5c37dfc527c4fd0e7b2871819b9e2dd7d5f57d5e3f0b

data/.rubocop.yml

@@ -1,5 +1,7 @@
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.1
+  NewCops: disable
+  SuggestExtensions: false
 
 Style/StringLiterals:
   Enabled: true
@@ -11,3 +13,33 @@ Style/StringLiteralsInInterpolation:
 
 Layout/LineLength:
   Max: 120
+
+Style/Documentation:
+  Exclude:
+    - "lib/bitwise_attributes/active_record_extension.rb"
+    - "spec/**/*"
+
+Metrics/ModuleLength:
+  Exclude:
+    - "lib/bitwise_attributes/active_record_extension.rb"
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "lib/bitwise_attributes/active_record_extension.rb"
+
+Metrics/MethodLength:
+  Exclude:
+    - "lib/bitwise_attributes/active_record_extension.rb"
+
+Metrics/AbcSize:
+  Exclude:
+    - "lib/bitwise_attributes/active_record_extension.rb"
+
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - "lib/bitwise_attributes/active_record_extension.rb"
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - "lib/bitwise_attributes/active_record_extension.rb"

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-05
+
+### Added
+- `toggle_key_bit` instance method (XOR) for each defined key
+- `with_all_attr(keys)` scope — "all of these bits are set" (any additional bits are also OK)
+- `with_exactly_attr(keys)` scope — true exact equality (`WHERE column = bitmask`)
+- Array-based setter: `record.attr = [:key_a, :key_b]` computes and assigns the bitmask; `nil` maps to `0`; raw integers pass through unchanged
+- `validates_bitwise_attribute(attr, **options)` class macro — adds a numericality validation ensuring the stored integer is between `0` and the maximum possible bitmask for that attribute
+- Overflow guard at definition time: raises `ArgumentError` when key count exceeds 62; warns to stderr when it exceeds 30 (recommend BIGINT column)
+- Validates that at least one key is provided and that no duplicate keys are present when calling `bitwise_attribute`
+
+### Changed
+- `with_exact_attr` renamed to `with_all_attr` — the old name implied exact column equality but the SQL performs a "has all" check; `with_exactly_attr` is the new true-exact scope
+- Column names are now quoted via `connection.quote_column_name` in all three SQL scopes for cross-adapter correctness
+- Scope lambdas capture the model class at definition time instead of using `ActiveRecord::Relation#model` at query time
+- Error messages from invalid key lookups now report only the unrecognised keys, not the full input array
+- `normalize_and_fetch_values` is now a public class method (no longer bypassed with `send` from instance context)
+- `update_bitwise_attribute` is now a private instance method
+
+### Fixed
+- Nil safety: all bitwise operations now call `.to_i` on the raw attribute value, preventing `NoMethodError` when the column is `NULL` or the record is unsaved
+
 ## [0.1.0] - 2026-07-05
 
 ### Added

data/CLAUDE.md

@@ -52,12 +52,16 @@ A single integer column stores multiple boolean flags packed as bits. Each flag
 |---|---|
 | `key_bit?` | Check if a specific bit is set |
 | `set_key_bit` / `unset_key_bit` | Set or clear a single bit |
+| `toggle_key_bit` | XOR-flip a single bit |
 | `attr_name_key` / `attr_name_key=` | Boolean getter/setter (accepts truthy values) |
 | `was_previously_key_bit?` | Dirty-tracking: was bit set before last save |
+| `attr_name=` | Assign full flag set from an `Array`, `Integer`, or `nil` |
 | `associated_attr_name` | Returns array of all currently-set key names |
 | `set_attr_name(*keys)` / `unset_attr_name(*keys)` | Bulk OR-in / AND-NOT-out |
+| `validates_bitwise_attribute(attr, **opts)` | Class macro: numericality validation (0..max_bitmask) |
 | `with_attr_name(keys)` | Scope: any of the given bits set |
-| `with_exact_attr_name(keys)` | Scope: exactly these bits set |
+| `with_all_attr_name(keys)` | Scope: all of the given bits set (other bits may also be set) |
+| `with_exactly_attr_name(keys)` | Scope: column equals the bitmask exactly |
 | `without_attr_name(keys)` | Scope: none of the given bits set |
 
 ### Aliases
@@ -76,4 +80,4 @@ Aliases are resolved transparently in scopes and bulk set/unset operations.
 
 ## RuboCop
 
-Configured in `.rubocop.yml`: Ruby 2.6 target, double-quoted strings enforced, max line length 120.
+Configured in `.rubocop.yml`: Ruby 3.1 target, double-quoted strings enforced, max line length 120.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    bitwise_attributes (0.1.0)
+    bitwise_attributes (0.2.0)
       activerecord (>= 6.1.7.3, < 9)
       activesupport (>= 6.1.7.3, < 9)
 

data/README.md

@@ -51,6 +51,7 @@ For each key the following methods are generated (shown for `read`):
 user.read_bit?                # => true / false
 user.set_read_bit             # sets the bit in memory
 user.unset_read_bit           # clears the bit in memory
+user.toggle_read_bit          # XOR — flips the bit
 
 user.permissions_read         # alias for read_bit?
 user.permissions_read = true  # accepts any truthy/falsy value
@@ -65,19 +66,35 @@ user.was_previously_read_bit? # dirty-tracking: state before last save
 user.set_permissions(:read, :admin)    # OR-in multiple bits
 user.unset_permissions(:write)         # AND-NOT-out multiple bits
 
+user.permissions = [:read, :admin]     # assign the full set from an array
+user.permissions = 5                   # raw integer passthrough also accepted
+
 user.associated_permissions            # => ["read", "admin"]
 user.permissions_values                # => {"read"=>1, "write"=>2, "admin"=>4}
 ```
 
+### Validation
+
+```ruby
+class User < ApplicationRecord
+  include BitwiseAttributes
+  bitwise_attribute :permissions, :read, :write, :admin
+  validates_bitwise_attribute :permissions            # 0..7, integer only
+  validates_bitwise_attribute :flags, allow_nil: true # passes Rails validator options through
+end
+```
+
 ### Scopes
 
 ```ruby
-User.with_permissions(:read)               # any of the given bits set
+User.with_permissions(:read)                    # any of the given bits set
 User.with_permissions([:read, :write])
 
-User.with_exact_permissions([:read, :write])  # ALL given bits set (superset)
+User.with_all_permissions([:read, :write])      # ALL given bits set (other bits may also be set)
+
+User.with_exactly_permissions([:read, :write])  # column = bitmask exactly (no other bits)
 
-User.without_permissions(:admin)           # none of the given bits set
+User.without_permissions(:admin)                # none of the given bits set
 ```
 
 ### Aliases

data/bitwise_attributes.gemspec

@@ -9,7 +9,9 @@ Gem::Specification.new do |spec|
   spec.email = ["mehboob.ali@7vals.com"]
 
   spec.summary = "Store multiple boolean flags in a single integer column using bitwise operations."
-  spec.description = "BitwiseAttributes extends ActiveRecord models with a bitwise_attribute DSL that packs multiple boolean flags into a single integer column, generating per-flag getter/setter methods and query scopes automatically."
+  spec.description = "BitwiseAttributes extends ActiveRecord models with a bitwise_attribute DSL that packs " \
+                     "multiple boolean flags into a single integer column, generating per-flag getter/setter " \
+                     "methods and query scopes automatically."
   spec.homepage = "https://github.com/mehboobali98/bitwise_attributes"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.1.4"

data/lib/bitwise_attributes/active_record_extension.rb

@@ -7,31 +7,39 @@ module BitwiseAttributes
     extend ActiveSupport::Concern
 
     class_methods do
-      # Define a bitwise attribute and dynamically generate methods and scopes
       def bitwise_attribute(attribute_name, *keys, aliases: {})
+        # C-03: reject empty or duplicate key lists up front
+        raise ArgumentError, "#{attribute_name}: at least one key is required" if keys.empty?
+
+        dupes = keys.tally.select { |_, n| n > 1 }.keys
+        raise ArgumentError, "#{attribute_name}: duplicate keys #{dupes.inspect}" if dupes.any?
+
+        # C-02: overflow guard — 32-bit INT holds 30 usable bits; BIGINT holds 62
+        if keys.size > 62
+          raise ArgumentError, "#{attribute_name}: #{keys.size} keys exceeds the 62-bit BIGINT limit"
+        elsif keys.size > 30
+          warn "[BitwiseAttributes] #{attribute_name} has #{keys.size} keys — use a BIGINT column to avoid overflow"
+        end
+
         invalid_aliases = aliases.values - keys
         raise ArgumentError, "Invalid aliases for #{attribute_name}: #{invalid_aliases}" if invalid_aliases.any?
 
-        bitwise_aliases[attribute_name]     = aliases.with_indifferent_access.freeze
-        bitwise_attributes[attribute_name]  = keys.map.with_index { |key, index| [key, 1 << index] }.to_h.with_indifferent_access.freeze
+        bitwise_aliases[attribute_name]    = aliases.with_indifferent_access.freeze
+        bitwise_attributes[attribute_name] = keys.map.with_index { |key, index| [key, 1 << index] }
+                                                     .to_h.with_indifferent_access.freeze
         define_bitwise_methods(attribute_name, keys)
       end
 
-      # Retrieve all defined bitwise aliases
       def bitwise_aliases
         @bitwise_aliases ||= Hash.new { |h, k| h[k] = {} }
       end
 
-      # Retrieve all defined bitwise attributes
       def bitwise_attributes
         @bitwise_attributes ||= {}
       end
 
-      # Ensure inheritance propagates bitwise attributes to subclasses
       def inherited(subclass)
         super
-
-        # Copy bitwise attributes to the subclass
         subclass.instance_variable_set(:@bitwise_aliases, bitwise_aliases.dup)
         subclass.instance_variable_set(:@bitwise_attributes, bitwise_attributes.dup)
       end
@@ -48,108 +56,138 @@ module BitwiseAttributes
         end
       end
 
+      # G-01: validation macro — ensures the stored integer cannot exceed the declared key space
+      def validates_bitwise_attribute(attribute_name, **options)
+        max_value = bitwise_attributes.fetch(attribute_name).values.sum
+        validates attribute_name,
+                  numericality: {
+                    only_integer: true,
+                    greater_than_or_equal_to: 0,
+                    less_than_or_equal_to: max_value
+                  },
+                  **options
+      end
+
+      # G-03: public so instance methods can call it without send
+      def normalize_and_fetch_values(attribute_name, keys)
+        alias_mappings   = bitwise_aliases[attribute_name]
+        attribute_values = bitwise_attributes[attribute_name]
+        Array(keys).uniq.map { |key| attribute_values[alias_mappings.fetch(key, key)] }
+      end
+
       private
 
-      # Dynamically define methods and scopes for a bitwise attribute
       def define_bitwise_methods(attribute_name, keys)
-        # Define a method to return the bitwise mapping for this attribute
-        define_method(:"#{attribute_name}_values") do
-          self.class.bitwise_attributes[attribute_name]
-        end
+        model_class = self # Q-03: capture at definition time; avoids using AR::Relation#model inside lambdas
 
-        define_method(:"#{attribute_name}_aliases") do
-          self.class.bitwise_aliases[attribute_name]
-        end
+        define_method(:"#{attribute_name}_values") { self.class.bitwise_attributes[attribute_name] }
+        define_method(:"#{attribute_name}_aliases") { self.class.bitwise_aliases[attribute_name] }
 
-        # Define methods for individual keys
         keys.each do |key|
           define_method(:"#{key}_bit?") do
             bit_value = send(:"#{attribute_name}_values")[key]
-            (self[attribute_name] & bit_value) != 0
+            (self[attribute_name].to_i & bit_value) != 0 # C-01: .to_i guards against NULL
           end
 
           define_method(:"set_#{key}_bit") do
             bit_value = send(:"#{attribute_name}_values")[key]
-            self[attribute_name] |= bit_value
+            self[attribute_name] = self[attribute_name].to_i | bit_value # C-01
           end
 
           define_method(:"unset_#{key}_bit") do
             bit_value = send(:"#{attribute_name}_values")[key]
-            self[attribute_name] &= ~bit_value
+            self[attribute_name] = self[attribute_name].to_i & ~bit_value # C-01
+          end
+
+          # A-02: XOR toggle — the most natural bitwise operation
+          define_method(:"toggle_#{key}_bit") do
+            bit_value = send(:"#{attribute_name}_values")[key]
+            self[attribute_name] = self[attribute_name].to_i ^ bit_value
           end
 
           define_method(:"#{attribute_name}_#{key}=") do |val|
             send(ActiveModel::Type::Boolean.new.cast(val) ? :"set_#{key}_bit" : :"unset_#{key}_bit")
           end
 
-          define_method(:"#{attribute_name}_#{key}") do
-            send(:"#{key}_bit?")
-          end
+          define_method(:"#{attribute_name}_#{key}") { send(:"#{key}_bit?") }
 
           define_method(:"was_previously_#{key}_bit?") do
             bit_value = send(:"#{attribute_name}_values")[key]
-            (attribute_previously_was(attribute_name) & bit_value) != 0
+            (attribute_previously_was(attribute_name).to_i & bit_value) != 0 # C-01
           end
         end
 
-        # Define helper methods for bulk operations
-        define_method(:"set_#{attribute_name}") do |*keys_to_add|
-          update_bitwise_attribute(attribute_name, keys_to_add, :add)
-        end
+        define_method(:"set_#{attribute_name}") { |*ks| update_bitwise_attribute(attribute_name, ks, :add) }
+        define_method(:"unset_#{attribute_name}") { |*ks| update_bitwise_attribute(attribute_name, ks, :remove) }
 
-        define_method(:"unset_#{attribute_name}") do |*keys_to_remove|
-          update_bitwise_attribute(attribute_name, keys_to_remove, :remove)
+        define_method(:"associated_#{attribute_name}") do
+          send(:"#{attribute_name}_values").reject { |_key, bit| (self[attribute_name].to_i & bit).zero? }.keys # C-01
         end
 
-        # Define method to retrieve associated keys
-        define_method(:"associated_#{attribute_name}") do
-          send(:"#{attribute_name}_values").reject { |_key, bit| (self[attribute_name] & bit).zero? }.keys
+        # A-04: assign the full flag set from an array or pass an integer through directly
+        define_method(:"#{attribute_name}=") do |value|
+          self[attribute_name] =
+            case value
+            when Integer  then value
+            when Array    then self.class.send(:calculate_bitmask, attribute_name, value.map(&:to_s))
+            when NilClass then 0
+            else raise ArgumentError, "Expected Integer or Array for #{attribute_name}, got #{value.class}"
+            end
         end
 
-        # Define dynamic scopes for filtering
+        # Q-01: quote column name via the adapter; Q-03: use captured model_class, not AR::Relation#model
         scope :"with_#{attribute_name}", lambda { |bit_keys|
-          bitmask = model.send(:calculate_bitmask, attribute_name, bit_keys)
-          where("#{attribute_name} & ? != 0", bitmask)
+          col     = model_class.connection.quote_column_name(attribute_name)
+          bitmask = model_class.send(:calculate_bitmask, attribute_name, bit_keys)
+          where("#{col} & ? != 0", bitmask)
         }
 
-        scope :"with_exact_#{attribute_name}", lambda { |bit_keys|
-          bitmask = model.send(:calculate_bitmask, attribute_name, bit_keys)
-          where("#{attribute_name} & :bitmask = :bitmask", { bitmask: bitmask })
+        # A-01: renamed from with_exact_ — semantics are "has ALL of these bits" (other bits may also be set)
+        scope :"with_all_#{attribute_name}", lambda { |bit_keys|
+          col     = model_class.connection.quote_column_name(attribute_name)
+          bitmask = model_class.send(:calculate_bitmask, attribute_name, bit_keys)
+          where("#{col} & :bitmask = :bitmask", { bitmask: bitmask })
+        }
+
+        # A-01: true exact equality — column value must equal the bitmask precisely
+        scope :"with_exactly_#{attribute_name}", lambda { |bit_keys|
+          bitmask = model_class.send(:calculate_bitmask, attribute_name, bit_keys)
+          where(attribute_name => bitmask)
         }
 
         scope :"without_#{attribute_name}", lambda { |bit_keys|
-          bitmask = model.send(:calculate_bitmask, attribute_name, bit_keys)
-          where("#{attribute_name} & ? = 0", bitmask)
+          col     = model_class.connection.quote_column_name(attribute_name)
+          bitmask = model_class.send(:calculate_bitmask, attribute_name, bit_keys)
+          where("#{col} & ? = 0", bitmask)
         }
       end
 
-      # Calculate the bitmask for given keys (now supports aliases)
       def calculate_bitmask(attribute_name, keys)
-        valid_values = normalize_and_fetch_values(attribute_name, keys)
-        raise ArgumentError, "Invalid #{attribute_name}: #{keys}" if valid_values.include?(nil)
+        # Q-02: zip so we can report only the unrecognised keys, not the whole input
+        unique_keys = Array(keys).uniq
+        values      = normalize_and_fetch_values(attribute_name, unique_keys)
+        invalid     = unique_keys.zip(values).filter_map { |k, v| k if v.nil? }
+        raise ArgumentError, "Unknown #{attribute_name} keys: #{invalid.inspect}" if invalid.any?
 
-        valid_values.sum
+        values.sum
       end
+    end
 
-      def normalize_and_fetch_values(attribute_name, keys)
-        alias_mappings    = bitwise_aliases[attribute_name]
-        attribute_values  = bitwise_attributes[attribute_name]
-
-        Array(keys).uniq.map { |key| attribute_values[alias_mappings.fetch(key, key)] }
-      end
+    # G-03: direct call — no send needed now that normalize_and_fetch_values is public on the class
+    def normalize_and_fetch_values(attribute_name, keys)
+      self.class.normalize_and_fetch_values(attribute_name, keys)
     end
 
-    # Update bitwise attributes for bulk add/remove operations
     def update_bitwise_attribute(attribute_name, keys, operation)
-      valid_values = send(:normalize_and_fetch_values, attribute_name, keys)
-      raise ArgumentError, "Invalid #{attribute_name}: #{keys}" if valid_values.include?(nil)
-
-      bitmask = valid_values.sum
-      self[attribute_name] = operation == :add ? (self[attribute_name] | bitmask) : (self[attribute_name] & ~bitmask)
+      bitmask = self.class.send(:calculate_bitmask, attribute_name, keys)
+      self[attribute_name] =
+        if operation == :add
+          self[attribute_name].to_i | bitmask   # C-01
+        else
+          self[attribute_name].to_i & ~bitmask  # C-01
+        end
     end
 
-    def normalize_and_fetch_values(attribute_name, keys)
-      self.class.send(:normalize_and_fetch_values, attribute_name, keys)
-    end
+    private :update_bitwise_attribute # A-03: internal helper — not part of the public instance API
   end
 end

data/lib/bitwise_attributes/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitwise_attributes
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Mehboob Ali