measured 2.8.2 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 808003a2689c157f3d3a1ef7ff2eb2f1decc242d23c40a536d9bca8c57364a79
-  data.tar.gz: 42f4a72969b5331d7cd460f87d5668b3b331001b82f351c221f7153488859be5
+  metadata.gz: b794b67ca5a9cc00444ec39526340e3f3710dc0395b7205aeb95f44d8ed698fe
+  data.tar.gz: 2696f28b014ce76cded21150a1e1b4ef4772ef92a358ddf4e99b526081125d2a
 SHA512:
-  metadata.gz: 4019bd9f128308af57f5ce9440e6a53f05587c1589f120b711c937b70d422a865c14d2e678d4b55bb13054e24a2663b5cb6ef51bfad12e834027eb4a644d5651
-  data.tar.gz: caf36d6ad0dbbd0e187adbb0d5a2ddd2718a38ddd67920e628c1d7ad09423f9c35edcef7f05cb863fec8e2849bb0eb8ce4145496aa0749cf2aaafbcd6459ba13
+  metadata.gz: 95c82144964349b7111b6a1d372384dc3721b3c5e79870c8b841b7468d6794f60702c2acb1be714fab6c5a858a26d0bc28c340ef987c61a5d94658ffd64eec25
+  data.tar.gz: 49b6f68fd80cce3886824df3298c2d837ec0f257b0e4bb311231558b0d9a81eb9cb744f3746540eeaa740f6ad1f84bb578441fc6914841ac81ae57005638a1c0

data/.github/workflows/ci.yml

@@ -10,14 +10,20 @@ jobs:
     strategy:
       matrix:
         ruby:
-          - '2.6'
-          - '2.7'
           - '3.0'
+          - '3.1'
+          - '3.2'
         gemfile:
           - Gemfile
-          - gemfiles/activesupport-5.2.gemfile
-          - gemfiles/activesupport-6.0.gemfile
-          - gemfiles/activesupport-6.1.gemfile
+          - gemfiles/rails-6.0.gemfile
+          - gemfiles/rails-6.1.gemfile
+          - gemfiles/rails-7.0.gemfile
+          - gemfiles/rails-edge.gemfile
+        exclude:
+          # Rails Edge only supports Ruby >= 3.1
+          - ruby: '3.0'
+            gemfile: gemfiles/rails-edge.gemfile
+
     name: Ruby ${{ matrix.ruby }} ${{ matrix.gemfile }}
     steps:
       - uses: actions/checkout@v1

data/.github/workflows/cla.yml

@@ -0,0 +1,23 @@
+# .github/workflows/cla.yml
+name: Contributor License Agreement (CLA)
+
+on:
+  pull_request_target:
+    types: [opened, synchronize]
+  issue_comment:
+    types: [created]
+
+jobs:
+  cla:
+    runs-on: ubuntu-latest
+    if: |
+      (github.event.issue.pull_request
+        && !github.event.issue.pull_request.merged_at
+        && contains(github.event.comment.body, 'signed')
+      )
+      || (github.event.pull_request && !github.event.pull_request.merged)
+    steps:
+      - uses: Shopify/shopify-cla-action@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          cla-token: ${{ secrets.CLA_TOKEN }}

data/.ruby-version

@@ -0,0 +1 @@
+3.0.2

data/CHANGELOG.md

@@ -3,6 +3,14 @@ Unreleased
 
 
 
+3.0.0
+-----
+
+* Merge functionality of `measured-rails` into this gem. From this version on, this gem is able to automatically integrate with Active Record out of the box. (@paracycle)
+* Add `:gm` and `:gms` as aliases to weight. (@kushagra-03)
+* Adds support for initializing `Measured` objects with a rational value from string. (@dvisockas)
+* Make `Measured` initialization faster by avoiding string substitution in certain cases. (@bitwise-aiden)
+
 2.8.2
 -----
 

data/Gemfile

@@ -1,3 +1,5 @@
 source 'https://rubygems.org'
 
 gemspec
+
+gem "activerecord"

data/README.md

@@ -4,7 +4,7 @@ Encapsulates measurements with their units. Provides easy conversion between uni
 
 Lightweight and easily extensible to include other units and conversions. Conversions done with `Rational` for precision.
 
-The adapter to integrate `measured` with Ruby on Rails is in a separate [`measured-rails`](https://github.com/Shopify/measured-rails) gem.
+Since version 3.0.0, the adapter to integrate `measured` with Ruby on Rails is also a part of this gem. If you had been using [`measured-rails`](https://github.com/Shopify/measured-rails) for that functionality, you should now remove `measured-rails` from your gem file.
 
 ## Installation
 
@@ -158,6 +158,116 @@ Measured::Weight.new("3.14", "kg").format(with_conversion_string: false)
 > "3.14 kg"
 ```
 
+### Active Record
+
+This gem also provides an Active Record adapter for persisting and retrieving measurements with their units, and model validations.
+
+Columns are expected to have the `_value` and `_unit` suffix, and be `DECIMAL` and `VARCHAR`, and defaults are accepted. Customizing the column used to hold units is supported, see below for details.
+
+```ruby
+class AddWeightAndLengthToThings < ActiveRecord::Migration
+  def change
+    add_column :things, :minimum_weight_value, :decimal, precision: 10, scale: 2
+    add_column :things, :minimum_weight_unit, :string, limit: 12
+
+    add_column :things, :total_length_value, :decimal, precision: 10, scale: 2, default: 0
+    add_column :things, :total_length_unit, :string, limit: 12, default: "cm"
+  end
+end
+```
+
+A column can be declared as a measurement with its measurement subclass:
+
+```ruby
+class Thing < ActiveRecord::Base
+  measured Measured::Weight, :minimum_weight
+  measured Measured::Length, :total_length
+  measured Measured::Volume, :total_volume
+end
+```
+
+You can optionally customize the model's unit column by specifying it in the `unit_field_name` option, as follows:
+
+```ruby
+class ThingWithCustomUnitAccessor < ActiveRecord::Base
+  measured_length :length, :width, :height,     unit_field_name: :size_unit
+  measured_weight :total_weight, :extra_weight, unit_field_name: :weight_unit
+  measured_volume :total_volume, :extra_volume, unit_field_name: :volume_unit
+end
+```
+
+Similarly, you can optionally customize the model's value column by specifying it in the `value_field_name` option, as follows:
+
+```ruby
+class ThingWithCustomValueAccessor < ActiveRecord::Base
+  measured_length :length, value_field_name: :custom_length
+  measured_weight :total_weight, value_field_name: :custom_weight
+  measured_volume :volume, value_field_name: :custom_volume
+end
+```
+
+There are some simpler methods for predefined types:
+
+```ruby
+class Thing < ActiveRecord::Base
+  measured_weight :minimum_weight
+  measured_length :total_length
+  measured_volume :total_volume
+end
+```
+
+This will allow you to access and assign a measurement object:
+
+```ruby
+thing = Thing.new
+thing.minimum_weight = Measured::Weight.new(10, "g")
+thing.minimum_weight_unit     # "g"
+thing.minimum_weight_value    # 10
+```
+
+Order of assignment does not matter, and each property can be assigned separately and with mass assignment:
+
+```ruby
+params = { total_length_unit: "cm", total_length_value: "3" }
+thing = Thing.new(params)
+thing.total_length.to_s   # 3 cm
+```
+
+### Validations
+
+Validations are available:
+
+```ruby
+class Thing < ActiveRecord::Base
+  measured_length :total_length
+
+  validates :total_length, measured: true
+end
+```
+
+This will validate that the unit is defined on the measurement, and that there is a value.
+
+Rather than `true` the validation can accept a hash with the following options:
+
+* `message`: Override the default "is invalid" message.
+* `units`: A subset of units available for this measurement. Units must be in existing measurement.
+* `greater_than`
+* `greater_than_or_equal_to`
+* `equal_to`
+* `less_than`
+* `less_than_or_equal_to`
+
+All comparison validations require `Measured::Measurable` values, not scalars. Most of these options replace the `numericality` validator which compares the measurement/method name/proc to the column's value. Validations can also be combined with `presence` validator.
+
+**Note:** Validations are strongly recommended since assigning an invalid unit will cause the measurement to return `nil`, even if there is a value:
+
+```ruby
+thing = Thing.new
+thing.total_length_value = 1
+thing.total_length_unit = "invalid"
+thing.total_length  # nil
+```
+
 ## Units and conversions
 
 ### SI units support
@@ -269,7 +379,7 @@ Existing alternatives which were considered:
 * **Cons**
   * Opens up and modifies `Array`, `Date`, `Fixnum`, `Math`, `Numeric`, `String`, `Time`, and `Object`, then depends on those changes internally.
   * Lots of code to solve a relatively simple problem.
-  * No ActiveRecord adapter.
+  * No Active Record adapter.
 
 ### Gem: [quantified](https://github.com/Shopify/quantified)
 * **Pros**
@@ -278,7 +388,7 @@ Existing alternatives which were considered:
   * All math done with floats making it highly lossy.
   * All units assumed to be pluralized, meaning using unit abbreviations is not possible.
   * Not actively maintained.
-  * No ActiveRecord adapter.
+  * No Active Record adapter.
 
 ### Gem: [unitwise](https://github.com/joshwlewis/unitwise)
 * **Pros**
@@ -287,7 +397,7 @@ Existing alternatives which were considered:
 * **Cons**
   * Lots of code. Good code, but lots of it.
   * Many modifications to core types.
-  * ActiveRecord adapter exists but is written and maintained by a different person/org.
+  * Active Record adapter exists but is written and maintained by a different person/org.
   * Not actively maintained.
 
 ## Contributing

data/dev.yml

@@ -1,8 +1,7 @@
 name: measured
 
 up:
-  - ruby:
-      version: 3.0.2
+  - ruby
   - bundler
 
 commands:

data/gemfiles/{activesupport-6.0.gemfile → rails-6.0.gemfile}

@@ -3,3 +3,4 @@ source 'https://rubygems.org'
 gemspec path: '..'
 
 gem 'activesupport', '~> 6.0'
+gem "activerecord", '~> 6.0'

data/gemfiles/{activesupport-6.1.gemfile → rails-6.1.gemfile}

@@ -3,3 +3,4 @@ source 'https://rubygems.org'
 gemspec path: '..'
 
 gem 'activesupport', '~> 6.1'
+gem "activerecord", '~> 6.1'

data/gemfiles/rails-7.0.gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gemspec path: '..'
+
+gem 'activesupport', '~> 7.0'
+gem 'activerecord', '~> 7.0'

data/gemfiles/rails-edge.gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gemspec path: '..'
+
+gem 'activesupport', github: 'rails/rails', branch: 'main'
+gem 'activerecord', github: 'rails/rails', branch: 'main'

data/lib/measured/measurable.rb

@@ -17,6 +17,8 @@ class Measured::Measurable < Numeric
       value
     when Integer
       Rational(value)
+    when String
+      /\d+\/\d+/.match?(value) ? Rational(value) : BigDecimal(value)
     else
       BigDecimal(value)
     end
@@ -30,7 +32,7 @@ class Measured::Measurable < Numeric
       else
         value.to_f.to_s
       end
-      str.gsub(/\.0*\Z/, "")
+      /\.0*\Z/.match?(str) ? str.gsub(/\.0*\Z/, "") : str
     end.freeze
   end
 

data/lib/measured/rails/active_record.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Measured::Rails::ActiveRecord
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    def measured(measured_class, *fields)
+      options = fields.extract_options!
+      options = {}.merge(options)
+
+      measured_class = measured_class.constantize if measured_class.is_a?(String)
+      unless measured_class.is_a?(Class) && measured_class.ancestors.include?(Measured::Measurable)
+        raise Measured::Rails::Error, "Expecting #{ measured_class } to be a subclass of Measured::Measurable"
+      end
+
+      options[:class] = measured_class
+
+      fields.map(&:to_sym).each do |field|
+        raise Measured::Rails::Error, "The field #{ field } has already been measured" if measured_fields.key?(field)
+
+        measured_fields[field] = options
+
+        unit_field_name = if options[:unit_field_name]
+          measured_fields[field][:unit_field_name] = options[:unit_field_name].to_s
+        else
+          "#{ field }_unit"
+        end
+
+        value_field_name = if options[:value_field_name]
+          measured_fields[field][:value_field_name] = options[:value_field_name].to_s
+        else
+          "#{ field }_value"
+        end
+
+        # Reader to retrieve measured object
+        define_method(field) do
+          value = public_send(value_field_name)
+          unit = public_send(unit_field_name)
+
+          return nil unless value && unit
+
+          instance = instance_variable_get("@measured_#{ field }") if instance_variable_defined?("@measured_#{ field }")
+          new_instance = begin
+            measured_class.new(value, unit)
+          rescue Measured::UnitError
+            nil
+          end
+
+          if instance == new_instance
+            instance
+          else
+            instance_variable_set("@measured_#{ field }", new_instance)
+          end
+        end
+
+        # Writer to assign measured object
+        define_method("#{ field }=") do |incoming|
+          if incoming.is_a?(measured_class)
+            instance_variable_set("@measured_#{ field }", incoming)
+            precision = self.column_for_attribute(value_field_name).precision
+            scale = self.column_for_attribute(value_field_name).scale
+            rounded_to_scale_value = incoming.value.round(scale)
+
+            max = self.class.measured_fields[field][:max_on_assignment]
+            if max && rounded_to_scale_value > max
+              rounded_to_scale_value = max
+            elsif rounded_to_scale_value.to_i.to_s.length > (precision - scale)
+              raise Measured::Rails::Error, "The value #{rounded_to_scale_value} being set for column '#{value_field_name}' has too many significant digits. Please ensure it has no more than #{precision - scale} significant digits."
+            end
+
+            public_send("#{ value_field_name }=", rounded_to_scale_value)
+            public_send("#{ unit_field_name }=", incoming.unit.name)
+          else
+            instance_variable_set("@measured_#{ field }", nil)
+            public_send("#{ value_field_name}=", nil)
+            public_send("#{ unit_field_name }=", nil)
+          end
+        end
+
+        # Writer to override unit assignment
+        redefine_method("#{ unit_field_name }=") do |incoming|
+          unit_name = measured_class.unit_system.unit_for(incoming).try!(:name)
+          write_attribute(unit_field_name, unit_name || incoming)
+        end
+      end
+    end
+
+    def measured_fields
+      @measured_fields ||= {}
+    end
+
+  end
+
+  module Length
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def measured_length(*fields)
+        measured(Measured::Length, *fields)
+      end
+    end
+  end
+
+  module Volume
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def measured_volume(*fields)
+        measured(Measured::Volume, *fields)
+      end
+    end
+  end
+
+  module Weight
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def measured_weight(*fields)
+        measured(Measured::Weight, *fields)
+      end
+    end
+  end
+end
+
+::ActiveRecord::Base.include(
+  Measured::Rails::ActiveRecord,
+  Measured::Rails::ActiveRecord::Length,
+  Measured::Rails::ActiveRecord::Volume,
+  Measured::Rails::ActiveRecord::Weight,
+)

data/lib/measured/rails/validations.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "active_model/validations"
+
+class MeasuredValidator < ActiveModel::EachValidator
+  CHECKS = {
+    greater_than: :>,
+    greater_than_or_equal_to: :>=,
+    equal_to: :==,
+    less_than: :<,
+    less_than_or_equal_to: :<=,
+  }.freeze
+
+  def validate_each(record, attribute, measurable)
+    measured_config = record.class.measured_fields[attribute]
+    unit_field_name = measured_config[:unit_field_name] || "#{ attribute }_unit"
+    value_field_name = measured_config[:value_field_name] || "#{ attribute }_value"
+
+    measured_class = measured_config[:class]
+
+    measurable_unit_name = record.public_send(unit_field_name)
+    measurable_value = record.public_send(value_field_name)
+
+    return unless measurable_unit_name.present? || measurable_value.present?
+
+    measurable_unit = measured_class.unit_system.unit_for(measurable_unit_name)
+    record.errors.add(attribute, message(record, "is not a valid unit")) unless measurable_unit
+
+    if options[:units] && measurable_unit.present?
+      valid_units = Array(options[:units]).map { |unit| measured_class.unit_system.unit_for(unit) }
+      record.errors.add(attribute, message(record, "is not a valid unit")) unless valid_units.include?(measurable_unit)
+    end
+
+    if measurable_unit && measurable_value.present?
+      options.slice(*CHECKS.keys).each do |option, value|
+        comparable_value = value_for(value, record)
+        comparable_value = measured_class.new(comparable_value, measurable_unit) unless comparable_value.is_a?(Measured::Measurable)
+        unless measurable.public_send(CHECKS[option], comparable_value)
+          record.errors.add(attribute, message(record, "#{measurable.to_s} must be #{CHECKS[option]} #{comparable_value}"))
+        end
+      end
+    end
+  end
+
+  private
+
+  def message(record, default_message)
+    if options[:message].respond_to?(:call)
+      options[:message].call(record)
+    else
+      options[:message] || default_message
+    end
+  end
+
+  def value_for(key, record)
+    value = case key
+    when Proc
+      key.call(record)
+    when Symbol
+      record.send(key)
+    else
+      key
+    end
+
+    raise ArgumentError, ":#{ value } must be a number or a Measurable object" unless (value.is_a?(Numeric) || value.is_a?(Measured::Measurable))
+    value
+  end
+end

data/lib/measured/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Measured
+  class Rails < ::Rails::Railtie
+    class Error < StandardError ; end
+
+    ActiveSupport.on_load(:active_record) do
+      require "measured/rails/active_record"
+      require "measured/rails/validations"
+    end
+  end
+end

data/lib/measured/units/weight.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 Measured::Weight = Measured.build do
-  si_unit :g, aliases: [:gram, :grams]
+  si_unit :g, aliases: [:gram, :grams, :gm, :gms]
 
   unit :t, value: "1000 kg", aliases: [:metric_ton, :metric_tons]
   unit :slug, value: "14.593903 kg", aliases: [:slugs]

data/lib/measured/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Measured
-  VERSION = "2.8.2"
+  VERSION = "3.0.0"
 end

data/lib/measured.rb

@@ -4,3 +4,5 @@ require "measured/base"
 require "measured/units/length"
 require "measured/units/weight"
 require "measured/units/volume"
+
+require "measured/railtie" if defined?(Rails::Railtie)

data/lib/tapioca/dsl/compilers/measured_rails.rb

@@ -0,0 +1,110 @@
+# typed: strict
+# frozen_string_literal: true
+
+return unless defined?(::Measured::Rails)
+
+module Tapioca
+  module Dsl
+    module Compilers
+      # `Tapioca::Dsl::Compilers::MeasuredRails` refines RBI files for subclasses of
+      # [`ActiveRecord::Base`](https://api.rubyonrails.org/classes/ActiveRecord/Base.html)
+      # that utilize the [`measured-rails`](https://github.com/shopify/measured-rails) DSL.
+      # This compiler is only responsible for defining the methods that would be created
+      # for measured fields that are defined in the Active Record model.
+      #
+      # For example, with the following model class:
+      #
+      # ~~~rb
+      # class Package < ActiveRecord::Base
+      #   measured Measured::Weight, :minimum_weight
+      #   measured Measured::Length, :total_length
+      #   measured Measured::Volume, :total_volume
+      # end
+      # ~~~
+      #
+      # this compiler will produce the following methods in the RBI file
+      # `package.rbi`:
+      #
+      # ~~~rbi
+      # # package.rbi
+      # # typed: true
+      #
+      # class Package
+      #   include GeneratedMeasuredRailsMethods
+      #
+      #   module GeneratedMeasuredRailsMethods
+      #     sig { returns(T.nilable(Measured::Weight)) }
+      #     def minimum_weight; end
+      #
+      #     sig { params(value: T.nilable(Measured::Weight)).void }
+      #     def minimum_weight=(value); end
+      #
+      #     sig { returns(T.nilable(Measured::Length)) }
+      #     def total_length; end
+      #
+      #     sig { params(value: T.nilable(Measured::Length)).void }
+      #     def total_length=(value); end
+      #
+      #     sig { returns(T.nilable(Measured::Volume)) }
+      #     def total_volume; end
+      #
+      #     sig { params(value: T.nilable(Measured::Volume)).void }
+      #     def total_volume=(value); end
+      #   end
+      # end
+      # ~~~
+      class MeasuredRails < ::Tapioca::Dsl::Compiler
+        extend T::Sig
+
+        ConstantType = type_member { {
+          fixed: T.all(
+            T.class_of(::ActiveRecord::Base),
+            ::Measured::Rails::ActiveRecord::ClassMethods
+          )
+        } }
+
+        MeasuredMethodsModuleName = T.let("GeneratedMeasuredRailsMethods", String)
+
+        sig { override.void }
+        def decorate
+          return if constant.measured_fields.empty?
+
+          root.create_path(constant) do |model|
+            model.create_module(MeasuredMethodsModuleName) do |mod|
+              populate_measured_methods(mod)
+            end
+
+            model.create_include(MeasuredMethodsModuleName)
+          end
+        end
+
+        sig { override.returns(T::Enumerable[Module]) }
+        def self.gather_constants
+          descendants_of(::ActiveRecord::Base)
+        end
+
+        private
+
+        sig { params(model: RBI::Scope).void }
+        def populate_measured_methods(model)
+          constant.measured_fields.each do |field, attrs|
+            class_name = qualified_name_of(attrs[:class])
+
+            next unless class_name
+
+            model.create_method(
+              field.to_s,
+              return_type: as_nilable_type(class_name)
+            )
+
+            model.create_method(
+              "#{field}=",
+              parameters: [create_param("value", type: as_nilable_type(class_name))],
+              return_type: "void"
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/measured.gemspec

@@ -13,6 +13,8 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/Shopify/measured"
   spec.license       = "MIT"
 
+  spec.required_ruby_version = ">= 3.0.0"
+
   # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
   # delete this section to allow pushing this gem to any host.
   if spec.respond_to?(:metadata)
@@ -33,4 +35,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "minitest-reporters"
   spec.add_development_dependency "mocha", ">= 1.4.0"
   spec.add_development_dependency "pry"
+  spec.add_development_dependency "combustion"
+  spec.add_development_dependency "sqlite3", "~> 1.4"
+  spec.add_development_dependency "tapioca"
 end

data/test/internal/app/models/thing.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+class Thing < ActiveRecord::Base
+
+  measured_length :length, :width
+
+  measured Measured::Length, :height
+  measured Measured::Volume, :volume
+
+  measured_weight :total_weight
+
+  measured "Measured::Weight", :extra_weight
+
+  measured_length :length_with_max_on_assignment, {max_on_assignment: 500}
+end