bonkers-bitfields 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c1c757381a66cc87dd65a60dc30fdcce2a4d937d368ab919bf3de33fe6d3629
+  data.tar.gz: 0be0ec980184561847d76fbfd1c5c8b00eb84638223fc055f18b22a1ad5b7057
+SHA512:
+  metadata.gz: f8bb243863c98d585f5924e3aa58c56b66480404c72218f5dec46aedc8b9fae560f09a314390ee9069e8f4bfc23518de2ed177467842e64c0e86b327a152ffd2
+  data.tar.gz: eac346b8c6b45836024ce89002cdf4b60ca278f2f126f5f45525a98ddf7f1f943117c6cdd7ca62375d5b83b25b8c9cff0d8c24a922e76e2fba6332558194b3ca

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed (breaking)
+- **Renamed the published gem to `bonkers-bitfields`.** The required library path
+  (`require "bitfields"`) and the `Bitfields` module are unchanged, so `include Bitfields`
+  and all generated methods keep working — only the `Gemfile` entry changes.
+- **Positional bit declarations now warn by default.** `bitfield :flags, :a, :b, :c` maps each
+  symbol to `2**index`, so inserting, removing, or reordering a symbol silently shifts every later
+  bit. The new `Bitfields.positional_bits` setting controls this: `:warn` (default) emits a
+  warning, `:forbid` raises, `:allow` restores the old silent behaviour. Prefer the explicit
+  `bitfield :flags, 1 => :a, 2 => :b, 4 => :c` form, which locks each name to its bit.
+- **Duplicate bit names across columns now raise `DuplicateBitNameError` at declaration time.**
+  Previously a name reused in two columns silently resolved to the first column. Bit names must be
+  unique per model.
+
+### Added
+- `Bitfields.positional_bits` configuration (`:warn` / `:forbid` / `:allow`).
+- `nil` / `:_skip` placeholders are allowed in positional declarations to reserve a bit position
+  without shifting later bits.
+- `with_bitfields` / `without_bitfields` class query methods (resolves the long-standing README
+  TODO), built on Arel so they survive eager-load table aliasing (resolves
+  [#45](https://github.com/grosser/bitfields/issues/45)).
+- GitHub Actions CI (`.github/workflows/ci.yml`) now lints and runs the test matrix on **every
+  branch** as well as pull requests, with concurrent superseded runs cancelled.
+- Release workflow (`.github/workflows/release.yml`) that publishes the gem to RubyGems via
+  [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) (OIDC, no stored API key)
+  when a `v*` tag is pushed.
+
+### Fixed
+- Cross-column duplicate bit names no longer silently misbehave
+  ([#21](https://github.com/grosser/bitfields/issues/21)).
+- README SQL examples (`(users.my_bits & 6) = 2`; `users.my_bits` table reference).
+- Duplicated assertion line in the RSpec `have_a_bitfield` matcher.
+
+### Removed
+- Travis CI (replaced with GitHub Actions) and the `wwtd` development dependency.
+- Support for Ruby < 3.1 and ActiveRecord < 6.1.

data/README.md

@@ -0,0 +1,216 @@
+# bonkers-bitfields
+
+[![CI](https://github.com/bonkers-ie/bitfields/actions/workflows/ci.yml/badge.svg)](https://github.com/bonkers-ie/bitfields/actions/workflows/ci.yml)
+
+Save migrations and columns by storing multiple booleans in a single integer.<br/>
+e.g. true-false-false = 1, false-true-false = 2,  true-false-true = 5 (1,2,4,8,..)
+
+> This is a maintained fork of [grosser/bitfields](https://github.com/grosser/bitfields),
+> published on RubyGems as **`bonkers-bitfields`**. The library is still required as
+> `bitfields` and the module is still `Bitfields`, so existing code does not change.
+
+```ruby
+class User < ActiveRecord::Base
+  include Bitfields
+  bitfield :flags, 1 => :vendor, 2 => :zany, 4 => :interesting
+end
+
+user = User.new(vendor: true, zany: true)
+user.vendor # => true
+user.interesting? # => false
+user.flags # => 3
+```
+
+### Always declare explicit bits
+
+`bitfield :flags, 1 => :vendor, 2 => :zany, 4 => :interesting` maps each name to an explicit bit,
+so the mapping is locked even if you reorder the list. The positional shorthand
+`bitfield :flags, :vendor, :zany, :interesting` instead maps each name to `2**index`, which means
+**inserting, removing, or reordering a name silently shifts every later bit and corrupts stored
+data**. By default a positional declaration now emits a warning; see
+[`Bitfields.positional_bits`](#positional-bit-safety).
+
+ - records bitfield_changes `user.bitfield_changes # => {"vendor" => [false, true], "zany" => [false, true]}` (also `vendor_was` / `vendor_change` / `vendor_changed?` / `vendor_became_true?` / `vendor_became_false?`)
+   - Individual added methods (i.e, `vendor_was`, `vendor_changed?`, etc..) can be deactivated with `bitfield ..., added_instance_methods: false`
+   - **Note**: when used in the context of an `after_save` callback, `_was` returns the current value and `_changed?` returns `false`, since the previous changes have been persisted.
+ - convenient queries `User.with_bitfields(vendor: true, zany: false)` and `User.without_bitfields(vendor: true)`
+ - adds scopes `User.vendor.interesting.first` (deactivate with `bitfield ..., scopes: false`)
+ - builds sql `User.bitfield_sql(zany: true, interesting: false) # => '(users.flags & 6) = 2'`
+ - builds sql with OR condition `User.bitfield_sql({ zany: true, interesting: true }, query_mode: :bit_operator_or) # => '(users.flags & 2) = 2 OR (users.flags & 4) = 4'`
+ - builds index-using sql with `bitfield ... , query_mode: :in_list` and `User.bitfield_sql(zany: true, interesting: false) # => 'users.flags IN (2, 3)'` (2 and 1+2) often slower than :bit_operator sql especially for high number of bits
+ - builds update sql `User.set_bitfield_sql(zany: true, interesting: false) == 'flags = (flags | 6) - 4'`
+ - **faster sql than any other bitfield lib** through combination of multiple bits into a single sql statement
+ - gives access to bits `User.bitfields[:flags][:interesting] # => 4`
+ - converts hash to bits `User.bitfield_bits(vendor: true) # => 1`
+
+Bit names must be unique per model: declaring the same name in two columns raises
+`Bitfields::DuplicateBitNameError`.
+
+Install
+=======
+
+```bash
+gem install bonkers-bitfields
+```
+
+```ruby
+# Gemfile
+gem "bonkers-bitfields"
+```
+
+```ruby
+require "bitfields" # the library path and the Bitfields module are unchanged
+```
+
+### Migration
+ALWAYS set a default, bitfield queries will not work for NULL
+
+```ruby
+t.integer :flags, default: 0, null: false
+# OR
+add_column :users, :flags, :integer, default: 0, null: false
+```
+
+Instance Methods
+================
+
+### Global Bitfield Methods
+| Method Name        | Example (`user = User.new(vendor: true, zany: true`)  | Result                                                      |
+|--------------------|---------------------------------------------------------|-------------------------------------------------------------|
+| `bitfield_values`  | `user.bitfield_values`                                  | `{"vendor" => true, "zany" => true, "interesting" => false}` |
+| `bitfield_changes` | `user.bitfield_changes`                                 | `{"vendor" => [false, true], "zany" => [false, true]}`    |
+
+### Individual Bit Methods
+#### Model Getters / Setters
+| Method Name    | Example (`user = User.new`) | Result  |
+|----------------|-----------------------------|---------|
+| `#{bit_name}`  | `user.vendor`               | `false` |
+| `#{bit_name}=` | `user.vendor = true`        | `true`  |
+| `#{bit_name}?` | `user.vendor = true; user.vendor?` | `true`  |
+
+#### Dirty Methods:
+
+Some, not all, [`ActiveRecord::AttributeMethods::Dirty`](https://api.rubyonrails.org/classes/ActiveRecord/AttributeMethods/Dirty.html) and [`ActiveModel::Dirty`](https://api.rubyonrails.org/classes/ActiveModel/Dirty.html) methods can be used on each bitfield:
+
+##### Before Model Persistence
+| Method Name                        | Example (`user = User.new`)        | Result          |
+|------------------------------------|------------------------------------|-----------------|
+| `#{bit_name}_was`                  | `user.vendor_was`                  | `false`         |
+| `#{bit_name}_in_database`          | `user.vendor_in_database`          | `false`         |
+| `#{bit_name}_change`               | `user.vendor_change`               | `[false, true]` |
+| `#{bit_name}_change_to_be_saved`   | `user.vendor_change_to_be_saved`   | `[false, true]` |
+| `#{bit_name}_changed?`             | `user.vendor_changed?`             | `true`          |
+| `will_save_change_to_#{bit_name}?` | `user.will_save_change_to_vendor?` | `true`          |
+| `#{bit_name}_became_true?`         | `user.vendor_became_true?`         | `true`          |
+| `#{bit_name}_became_false?`        | `user.vendor_became_false?`        | `false`         |
+
+
+##### After Model Persistence
+| Method Name                    | Example (`user = User.create(vendor: true)`)      | Result          |
+|--------------------------------|---------------------------------------------------|-----------------|
+| `#{bit_name}_before_last_save` | `user.vendor_before_last_save`                    | `false`         |
+| `saved_change_to_#{bit_name}`  | `user.saved_change_to_vendor`                     | `[false, true]` |
+| `saved_change_to_#{bit_name}?` | `user.saved_change_to_vendor?`                    | `true`          |
+
+  - **Note**: These methods are dynamically defined for each bitfield, and function separately from the real `ActiveRecord::AttributeMethods::Dirty`/`ActiveModel::Dirty` methods. As such, generic methods (e.g. `attribute_before_last_save(:attribute)`) will not work.
+
+Examples
+========
+Update all users
+
+```ruby
+User.vendor.not_interesting.update_all(User.set_bitfield_sql(vendor: true, zany: true))
+```
+
+Delete the shop when a user is no longer a vendor
+
+```ruby
+before_save :delete_shop, if: -> { |u| u.vendor_change == [true, false] }
+```
+
+List fields and their respective values
+
+```ruby
+user = User.new(zany: true)
+user.bitfield_values(:flags) # => { vendor: false, zany: true, interesting: false }
+```
+
+Querying through associations
+
+```ruby
+# `with_bitfields` builds an Arel predicate, so it composes with eager loading. A raw string
+# condition would silently match nothing here on modern ActiveRecord.
+Team.includes(:members).references(:members).merge(User.with_bitfields(vendor: true))
+```
+
+<a name="positional-bit-safety"></a>
+Positional bit safety
+=====================
+Control how the positional shorthand (`bitfield :bits, :foo, :bar`) is treated:
+
+```ruby
+Bitfields.positional_bits = :warn   # default: warn that positional bits are fragile
+Bitfields.positional_bits = :forbid # raise Bitfields::PositionalBitsError instead
+Bitfields.positional_bits = :allow  # legacy behaviour, no warning
+```
+
+If you keep positional declarations, you can reserve a bit position with `nil` or `:_skip` so
+removing a bit does not shift the bits after it:
+
+```ruby
+bitfield :bits, :vendor, nil, :interesting # vendor => 1, interesting => 4 (bit 2 left unused)
+```
+
+TIPS
+====
+ - [Defaults for new records] set via db migration or name the bit foo_off to avoid confusion, setting via after_initialize [does not work](https://github.com/grosser/bitfields/commit/2170dc546e2c4f1187089909a80e8602631d0796)
+ - It is slow to do: `#{bitfield_sql(...)} AND #{bitfield_sql(...)}`, merge both into one hash
+ - bit_operator is faster in most cases, use `query_mode: :in_list` sparingly
+ - Standard mysql integer is 4 byte -> 32 bitfields
+ - Prefer explicit bits `bitfield :bits, 1 => :foo, 2 => :bar, 4 => :baz` (or `2**0 => :foo, 2**1 => :bar`) over the positional shorthand `bitfield :bits, :foo, :bar, :baz`
+
+Query-mode Benchmark
+=========
+The `query_mode: :in_list` is slower for most queries and scales miserably with the number of bits.<br/>
+*Stay with the default query-mode*. Only use :in_list if your edge-case shows better performance.
+
+Run the benchmark yourself with `ruby benchmark/bit_operator_vs_in.rb`: across 2–14 bits, `:bit_operator`
+stays roughly flat while `:in_list` grows steeply with the number of bits.
+
+Testing With RSpec
+=========
+
+To assert that a specific flag is a bitfield flag and has the `zany?`, `zany`, and `zany=` methods and behavior use the following matcher:
+
+````ruby
+require 'bitfields/rspec'
+
+describe User do
+  it { is_expected.to have_a_bitfield :zany }
+end
+````
+
+Supported versions
+===================
+Ruby >= 3.1 and ActiveRecord 6.1 – 8.0, tested on CI.
+
+Authors
+=======
+### [Contributors](https://github.com/bonkers-ie/bitfields/contributors)
+ - [Ben Walsh](https://github.com/benwalsh)
+ - [Hellekin O. Wolf](https://github.com/hellekin)
+ - [John Wilkinson](https://github.com/jcwilk)
+ - [PeppyHeppy](https://github.com/peppyheppy)
+ - [kmcbride](https://github.com/kmcbride)
+ - [Justin Aiken](https://github.com/JustinAiken)
+ - [szTheory](https://github.com/szTheory)
+ - [Reed G. Law](https://github.com/reedlaw)
+ - [Rael Gugelmin Cunha](https://github.com/reedlaw)
+ - [Alan Wong](https://github.com/naganowl)
+ - [Andrew Bates](https://github.com/a-bates)
+ - [Shirish Pampoorickal](https://github.com/shirish-pampoorickal)
+ - [Sergey Kojin](https://github.com/skojin)
+
+Originally by [Michael Grosser](http://grosser.it) (michael@grosser.it).<br/>
+Maintained as `bonkers-bitfields` by [Bonkers.ie](https://github.com/bonkers-ie).<br/>
+License: MIT

data/lib/bitfields/rspec.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define :have_a_bitfield do |field|
+  match do |klass|
+    klass.respond_to?(field) &&
+      klass.respond_to?("#{field}?") &&
+      klass.respond_to?("#{field}=")
+  end
+
+  failure_message do |klass|
+    "expected #{expected.join} to be a bitfield property defined on #{klass}"
+  end
+
+  failure_message_when_negated do |klass|
+    "expected #{expected.join} to NOT be a bitfield property defined on #{klass}"
+  end
+
+  description do
+    "be a bitfield on #{expected}"
+  end
+end

data/lib/bitfields/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Bitfields
+  VERSION = '1.0.0'
+  Version = VERSION
+end

data/lib/bitfields.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+require 'bitfields/version'
+require 'active_support'
+
+module Bitfields
+  TRUE_VALUES = [true, 1, '1', 't', 'T', 'true', 'TRUE'].freeze # taken from ActiveRecord::ConnectionAdapters::Column
+
+  # Symbols/values that reserve a positional bit without naming it, so removing a bit
+  # leaves a gap instead of silently shifting every later bit down.
+  POSITIONAL_PLACEHOLDERS = [nil, :_skip].freeze
+  POSITIONAL_MODES = %i[allow warn forbid].freeze
+
+  class DuplicateBitNameError < ArgumentError; end
+  class InvalidBitError < ArgumentError; end
+  class PositionalBitsError < ArgumentError; end
+
+  class << self
+    # How to treat the positional shorthand `bitfield :col, :a, :b` (maps each name to 2**index,
+    # so reordering/inserting/removing a name silently shifts stored bits):
+    #   :warn (default) - emit a warning, :forbid - raise, :allow - stay silent (legacy behaviour)
+    attr_writer :positional_bits
+
+    def positional_bits
+      @positional_bits ||= :warn
+    end
+
+    def included(base)
+      class << base
+        attr_accessor :bitfields, :bitfield_options, :bitfield_args
+
+        # all the args passed into .bitfield so children can initialize from parents
+        def bitfield_args
+          @bitfield_args ||= []
+        end
+
+        def inherited(subclass)
+          super
+          subclass.bitfield_args = bitfield_args.dup
+          subclass.bitfield_args.each do |column, options|
+            subclass.send :store_bitfield_values, column, options.dup
+          end
+        end
+      end
+
+      base.extend Bitfields::ClassMethods
+    end
+
+    def extract_bits(options)
+      options.keys.grep(Numeric).each_with_object({}) do |bit, bitfields|
+        unless bit.is_a?(Integer) && bit.positive? && bit.nobits?(bit - 1)
+          raise InvalidBitError, "#{bit} is not a power of 2 !!"
+        end
+
+        bit_name = options.delete(bit).to_sym
+        raise DuplicateBitNameError if bitfields.key?(bit_name)
+
+        bitfields[bit_name] = bit
+      end
+    end
+  end
+
+  module ClassMethods
+    def bitfield(column, *args)
+      column = column.to_sym
+      options = extract_bitfield_options(column, args)
+      bitfield_args << [column, options.dup]
+
+      store_bitfield_values column, options
+      add_bitfield_methods column, options
+    end
+
+    def bitfield_bits(values)
+      bits = bitfields.values.reduce({}, :merge)
+      values.sum { |bit, on| on ? bits.fetch(bit) : 0 }
+    end
+
+    def bitfield_column(bit_name)
+      found = bitfields.find { |_, bits| bits.key?(bit_name.to_sym) }
+      raise "Unknown bitfield #{bit_name}" unless found
+
+      found.first
+    end
+
+    def bitfield_sql(bit_values, options = {})
+      bits = group_bits_by_column(bit_values).sort_by { |column, _| column.to_s }
+      bits.map { |column, values| bitfield_sql_by_column(column, values, options) }.join(' AND ')
+    end
+
+    # rubocop:disable Naming/AccessorMethodName -- public API name, kept for backwards compatibility
+    def set_bitfield_sql(bit_values)
+      bits = group_bits_by_column(bit_values).sort_by { |column, _| column.to_s }
+      bits.map { |column, values| set_bitfield_sql_by_column(column, values) }.join(', ')
+    end
+    # rubocop:enable Naming/AccessorMethodName
+
+    # Arel-based predicate for the given bits. Unlike the string SQL built by bitfield_sql,
+    # an Arel predicate carries its table relation, so it composes with eager loading
+    # (`includes`/`references`/`merge`) without the silent no-match that strings cause on
+    # ActiveRecord >= 6.1.
+    def bitfield_arel(bit_values)
+      predicates = group_bits_by_column(bit_values).sort_by { |column, _| column.to_s }.map do |column, values|
+        bitfield_arel_by_column(column, values)
+      end
+      predicates.reduce(:and)
+    end
+
+    # Convenient named query: `User.with_bitfields(vendor: true, zany: false)`
+    def with_bitfields(bit_values)
+      where(bitfield_arel(bit_values))
+    end
+
+    def without_bitfields(bit_values)
+      where.not(bitfield_arel(bit_values))
+    end
+
+    private
+
+    def extract_bitfield_options(column, args)
+      options = args.last.is_a?(Hash) ? args.pop.dup : {}
+      return options if args.empty?
+
+      enforce_positional_policy(column)
+      args.each_with_index do |field, index|
+        next if POSITIONAL_PLACEHOLDERS.include?(field)
+
+        options[2**index] = field # add fields given in normal args to options
+      end
+      options
+    end
+
+    def enforce_positional_policy(column)
+      case Bitfields.positional_bits
+      when :allow then nil
+      when :warn then warn(positional_bits_message(column))
+      when :forbid then raise PositionalBitsError, positional_bits_message(column)
+      else raise ArgumentError, "Bitfields.positional_bits must be one of #{POSITIONAL_MODES.inspect}"
+      end
+    end
+
+    def positional_bits_message(column)
+      "#{name}: bitfield #{column.inspect} uses positional bit names, which silently shift stored " \
+        'bits if the list is reordered or an entry is removed. Declare explicit bits instead, ' \
+        "e.g. `bitfield #{column.inspect}, 1 => :first, 2 => :second`."
+    end
+
+    def store_bitfield_values(column, options)
+      self.bitfields ||= {}
+      self.bitfield_options ||= {}
+      extracted = Bitfields.extract_bits(options)
+      ensure_unique_bit_names!(column, extracted)
+      bitfields[column] = extracted
+      bitfield_options[column] = options
+    end
+
+    def ensure_unique_bit_names!(column, extracted)
+      taken = bitfields.except(column).values.flat_map(&:keys)
+      duplicate = extracted.keys.find { |bit_name| taken.include?(bit_name) }
+      return unless duplicate
+
+      raise DuplicateBitNameError,
+            "#{name}: bit name #{duplicate.inspect} is already defined on another bitfield column " \
+            '(bit names must be unique per model)'
+    end
+
+    def add_bitfield_methods(column, options)
+      bitfields[column].each_key do |bit_name|
+        if options[:added_instance_methods] != false
+          define_method(bit_name) { bitfield_value(bit_name) }
+          define_method("#{bit_name}?") { bitfield_value(bit_name) }
+          define_method("#{bit_name}=") { |value| set_bitfield_value(bit_name, value) }
+
+          # Dirty methods usable in before_save contexts
+          define_method("#{bit_name}_was") { bitfield_value_was(bit_name) }
+          alias_method "#{bit_name}_in_database", "#{bit_name}_was"
+
+          define_method("#{bit_name}_change") { bitfield_value_change(bit_name) }
+          alias_method "#{bit_name}_change_to_be_saved", "#{bit_name}_change"
+
+          define_method("#{bit_name}_changed?") { bitfield_value_change(bit_name).present? }
+          alias_method "will_save_change_to_#{bit_name}?", "#{bit_name}_changed?"
+
+          define_method("#{bit_name}_became_true?") do
+            value = bitfield_value(bit_name)
+            value && send("#{bit_name}_was") != value
+          end
+          define_method("#{bit_name}_became_false?") do
+            value = bitfield_value(bit_name)
+            !value && send("#{bit_name}_was") != value
+          end
+
+          # Dirty methods usable in after_save contexts
+          define_method("#{bit_name}_before_last_save") { bitfield_value_before_last_save(bit_name) }
+          define_method("saved_change_to_#{bit_name}") { saved_change_to_bitfield_value(bit_name) }
+          define_method("saved_change_to_#{bit_name}?") { saved_change_to_bitfield_value(bit_name).present? }
+        end
+
+        if options[:scopes] != false
+          scope bit_name, bitfield_scope_options(bit_name => true)
+          scope "not_#{bit_name}", bitfield_scope_options(bit_name => false)
+        end
+      end
+
+      include Bitfields::InstanceMethods
+    end
+
+    def bitfield_scope_options(bit_values)
+      -> { where(bitfield_arel(bit_values)) }
+    end
+
+    def bitfield_sql_by_column(column, bit_values, options = {})
+      mode = options[:query_mode] || bitfield_options[column][:query_mode] || :bit_operator
+      case mode
+      when :in_list
+        max = (bitfields[column].values.max * 2) - 1
+        bits = (0..max).to_a # all possible bits
+        bit_values.each do |bit_name, value|
+          bit = bitfields[column][bit_name]
+          # reject values with: bit off for true, bit on for false
+          bits.reject! { |i| i & bit == (value ? 0 : bit) }
+        end
+        "#{table_name}.#{column} IN (#{bits.join(',')})"
+      when :bit_operator
+        on, off = bit_values_to_on_off(column, bit_values)
+        "(#{table_name}.#{column} & #{on + off}) = #{on}"
+      when :bit_operator_or
+        on, off = bit_values_to_on_off(column, bit_values)
+        result = []
+        result << "(#{table_name}.#{column} & #{on}) <> 0" if on != 0
+        result << "(#{table_name}.#{column} & #{off}) <> #{off}" if off != 0
+        result.join(' OR ')
+      else raise("bitfields: unknown query mode #{mode.inspect}")
+      end
+    end
+
+    def set_bitfield_sql_by_column(column, bit_values)
+      on, off = bit_values_to_on_off(column, bit_values)
+      "#{column} = (#{column} | #{on + off}) - #{off}"
+    end
+
+    def bitfield_arel_by_column(column, bit_values)
+      attribute = arel_table[column]
+      on, off = bit_values_to_on_off(column, bit_values)
+      predicates = []
+      predicates << (attribute & on).eq(on) unless on.zero?
+      predicates << (attribute & off).eq(0) unless off.zero?
+      predicates.reduce(:and)
+    end
+
+    def group_bits_by_column(bit_values)
+      columns = {}
+      bit_values.each do |bit_name, value|
+        column = bitfield_column(bit_name.to_sym)
+        columns[column] ||= {}
+        columns[column][bit_name.to_sym] = value
+      end
+      columns
+    end
+
+    def bit_values_to_on_off(column, bit_values)
+      on = off = 0
+      bit_values.each do |bit_name, value|
+        bit = bitfields[column][bit_name]
+        value ? on += bit : off += bit
+      end
+      [on, off]
+    end
+  end
+
+  module InstanceMethods
+    def bitfield_values(column)
+      self.class.bitfields[column.to_sym].keys.to_h { |bit_name| [bit_name, bitfield_value(bit_name)] }
+    end
+
+    def bitfield_changes
+      self.class.bitfields.values.flat_map(&:keys).each_with_object({}) do |bit, changes|
+        old = bitfield_value_was(bit)
+        current = bitfield_value(bit)
+        changes[bit.to_s] = [old, current] unless old == current
+      end
+    end
+
+    private
+
+    def bitfield_value(bit_name)
+      _, bit, current_value = bitfield_info(bit_name)
+      current_value & bit != 0
+    end
+
+    def bitfield_value_was(bit_name)
+      column, bit, = bitfield_info(bit_name)
+      send("#{column}_was") & bit != 0
+    end
+
+    def bitfield_value_before_last_save(bit_name)
+      column, bit, = bitfield_info(bit_name)
+      column_before_last_save = send("#{column}_before_last_save")
+      column_before_last_save.nil? ? nil : column_before_last_save & bit != 0
+    end
+
+    def bitfield_value_change(bit_name)
+      values = [bitfield_value_was(bit_name), bitfield_value(bit_name)]
+      values unless values[0] == values[1]
+    end
+
+    def saved_change_to_bitfield_value(bit_name)
+      value_before_last_save = bitfield_value_before_last_save(bit_name)
+      current_value = bitfield_value(bit_name)
+      return if value_before_last_save.nil? || (value_before_last_save == current_value)
+
+      [value_before_last_save, current_value]
+    end
+
+    def set_bitfield_value(bit_name, value)
+      column, bit, current_value = bitfield_info(bit_name)
+      new_value = TRUE_VALUES.include?(value)
+      old_value = bitfield_value(bit_name)
+      return if new_value == old_value
+
+      # 8 + 1 == 9 // 8 + 8 == 8 // 1 - 8 == 1 // 8 - 8 == 0
+      new_bits = new_value ? current_value | bit : (current_value | bit) - bit
+      send("#{column}=", new_bits)
+    end
+
+    def bitfield_info(bit_name)
+      column = self.class.bitfield_column(bit_name)
+      [
+        column,
+        self.class.bitfields[column][bit_name], # bit
+        send(column) || 0 # current value
+      ]
+    end
+  end
+end

metadata

@@ -0,0 +1,166 @@
+--- !ruby/object:Gem::Specification
+name: bonkers-bitfields
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Michael Grosser
+- Bonkers.ie
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: bump
+  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'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  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'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  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'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  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'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  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'
+email: michael@grosser.it
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/bitfields.rb
+- lib/bitfields/rspec.rb
+- lib/bitfields/version.rb
+homepage: https://github.com/bonkers-ie/bitfields
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/bonkers-ie/bitfields
+  changelog_uri: https://github.com/bonkers-ie/bitfields/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/bonkers-ie/bitfields/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Save migrations and columns by storing multiple booleans in a single integer
+test_files: []