pico_phone-rails 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84738b06cba145a9e86bedc83516cd76511f8eeb275157a6807b22bc8b646c99
-  data.tar.gz: be4865cf109ea61e834dc4f69d24c7937de912872915bc7014947d12f53f2b3c
+  metadata.gz: a727b58fa9b03d91f9fed795d5f9b4898c8b6c1d416fa67eed38dc881c8a738a
+  data.tar.gz: 2727b559da6ec1a963f6b12f032aeeb9458eaacb5522e3ee98aabbb289863c28
 SHA512:
-  metadata.gz: d13dae58efa40a2d05affceb83b3da6c2b5f15576c9ee45c07856a1e0f31c83d7b483f2abed929ba1b205f6b7534cd615d0a3edb2958a39cd6e5a4741cbfb581
-  data.tar.gz: 1636311abdb2f94b9e7adac696d3ef6f13bcc7f3d840a8d40c935e4a9d6d498559c6df830dd1e11660d0c2ce455128864b930a1719815d6caf09450265850164
+  metadata.gz: f07be21c54bcd8f6f9f054af69875b7993f4428f6ef57a97d57252fcee3b71f540b1bcae6563568823c98960e4894afded9ec2e243178af10c36ff2a3dccca1d
+  data.tar.gz: 5b409b31ddbeaae09328eb1cbf6a98d392ad9cce01d5e047198c96149c6e985b9125baaa02c3557decbd1baacb6fc55e492203f9b9a76becd9386162474bad79

data/README.md

@@ -78,6 +78,11 @@ bundle exec appraisal install
 bundle exec appraisal rake
 ```
 
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub — see
+[CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines.
+
 ## License
 
 MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/phone_validator.rb

@@ -6,8 +6,20 @@
 # including model's namespace up through Object, same convention the
 # email_validator gem uses.
 #
+# @example
 #   validates :phone, phone: { region: "US", allow_blank: true }
+#
+# @example Looser "possible" check instead of full validity
+#   validates :phone, phone: { region: "US", possible: true }
 class PhoneValidator < ActiveModel::EachValidator
+  # @param record [ActiveModel::Validations]
+  # @param attribute [Symbol]
+  # @param value [String, PicoPhone::PhoneNumber, nil]
+  # @option options [String] :region ISO 3166-1 alpha-2 default region used to interpret national-format input
+  # @option options [Boolean] :allow_blank skip validation when +value+ is +nil+ or empty
+  # @option options [Boolean] :possible use a looser possible?/possible_for_country? check instead of strict validity
+  # @option options [String] :message custom error message, passed through to +errors.add+
+  # @return [void]
   def validate_each(record, attribute, value)
     return if options[:allow_blank] && value.blank?
 

data/lib/pico_phone/rails/normalizer.rb

@@ -8,6 +8,7 @@ module PicoPhone
     # class macro that rewrites the given attributes to E.164 before validation
     # runs, so validators and persisted data see a consistent format.
     #
+    # @example
     #   class Contact < ApplicationRecord
     #     normalize_phone :phone, region: "US"
     #   end
@@ -15,6 +16,13 @@ module PicoPhone
       extend ActiveSupport::Concern
 
       class_methods do
+        # @!method normalize_phone(*attributes, region: nil)
+        #   Registers a +before_validation+ callback that rewrites each attribute
+        #   to E.164 when it parses as valid, leaving unparseable input untouched
+        #   so a validator can flag it.
+        #   @param attributes [Array<Symbol>] attribute names to normalize
+        #   @param region [String, nil] ISO 3166-1 alpha-2 default region used to interpret national-format input
+        #   @return [void]
         def normalize_phone(*attributes, region: nil)
           before_validation do
             attributes.each do |attribute|

data/lib/pico_phone/rails/serializers/phone_number_serializer.rb

@@ -5,26 +5,34 @@ module PicoPhone
     module Serializers
       # Registered with ActiveJob::Serializers in the railtie, only once
       # ActiveJob itself has loaded. Lets a PhoneNumber survive as a job
-      # argument without the caller manually converting to/from a string:
-      #
-      #   MyJob.perform_later(phone: PicoPhone.parse("+15102745656", "US"))
+      # argument without the caller manually converting to/from a string.
       #
       # #to_s alone is enough to round-trip losslessly: E.164 is
       # region-independent for valid numbers, and for invalid/unparseable
       # input #to_s already falls back to the original string, which
       # reparses to the same #to_s/#valid? regardless of region.
+      #
+      # @example
+      #   MyJob.perform_later(phone: PicoPhone.parse("+15102745656", "US"))
       class PhoneNumberSerializer < ActiveJob::Serializers::ObjectSerializer
+        # @param phone_number [PicoPhone::PhoneNumber]
+        # @return [Hash] JSON-safe payload; ActiveJob merges in its own reserved serializer-identity key
         def serialize(phone_number)
           super("value" => phone_number.to_s)
         end
 
+        # @param hash [Hash] payload previously produced by {#serialize}
+        # @return [PicoPhone::PhoneNumber]
         def deserialize(hash)
           PicoPhone.parse(hash["value"])
         end
 
-        # Public since ActiveJob 8.1: Serializers.serializer_for builds a
-        # lookup index keyed by this, and warns (raising from 8.2 on) if
-        # it's private.
+        # The class this serializer handles -- ActiveJob::Serializers uses it
+        # both for dispatch (default #serialize?) and, since ActiveJob 8.1, to
+        # build a lookup index, which is why it must be public: earlier
+        # ActiveJob versions accepted a private #klass, but 8.1+ warns (and
+        # 8.2+ will raise) if it isn't public.
+        # @return [Class]
         def klass
           PicoPhone::PhoneNumber
         end

data/lib/pico_phone/rails/type.rb

@@ -7,17 +7,25 @@ module PicoPhone
     # Registered as `:phone_number` in the railtie. Casts a stored string to a
     # PicoPhone::PhoneNumber on read and serializes back to E.164 on write.
     #
+    # @example
     #   attribute :phone, :phone_number, region: "US"
+    #
+    #   contact.phone       # => #<PicoPhone::PhoneNumber ...>
+    #   contact.phone.e164  # => "+15102745656"
     class Type < ActiveModel::Type::Value
+      # @param region [String, nil] ISO 3166-1 alpha-2 default region used to interpret national-format input
       def initialize(region: nil)
         @region = region
         super()
       end
 
+      # @return [Symbol] always +:string+ -- the underlying column stores a plain string
       def type
         :string
       end
 
+      # @param value [String, PicoPhone::PhoneNumber, nil]
+      # @return [PicoPhone::PhoneNumber, nil] +nil+ for +nil+ input; never raises on unparseable input
       def cast(value)
         return value if value.is_a?(PicoPhone::PhoneNumber)
         return nil if value.nil?
@@ -25,6 +33,8 @@ module PicoPhone
         PicoPhone.parse(value.to_s, @region)
       end
 
+      # @param value [String, PicoPhone::PhoneNumber, nil]
+      # @return [String, nil] E.164 for a valid number, the original string for an invalid one, +nil+ for +nil+ input
       def serialize(value)
         return nil if value.nil?
 
@@ -32,6 +42,8 @@ module PicoPhone
         phone_number.valid? ? phone_number.e164 : phone_number.to_s
       end
 
+      # @param value [String, nil] raw value read from the database
+      # @return [PicoPhone::PhoneNumber, nil]
       def deserialize(value)
         cast(value)
       end

data/lib/pico_phone/rails/version.rb

@@ -2,6 +2,6 @@
 
 module PicoPhone
   module Rails
-    VERSION = "0.2.0"
+    VERSION = "0.2.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pico_phone-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Gabi Jack
@@ -52,8 +52,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '7.0'
 description: 'pico_phone-rails wires the pico_phone gem into Rails: a :phone_number
-  ActiveRecord attribute type, a PhoneValidator for ActiveModel validations, and a
-  normalize_phone class macro that rewrites phone attributes to E.164 before validation.'
+  ActiveRecord attribute type, a PhoneValidator for ActiveModel validations, a normalize_phone
+  class macro that rewrites phone attributes to E.164 before validation, and an ActiveJob
+  serializer so a PhoneNumber survives being passed as a job argument.'
 email:
 - gabi@gabijack.com
 executables: []
@@ -78,6 +79,7 @@ metadata:
   source_code_uri: https://github.com/gjack/pico_phone-rails
   changelog_uri: https://github.com/gjack/pico_phone-rails/releases
   bug_tracker_uri: https://github.com/gjack/pico_phone-rails/issues
+  documentation_uri: https://rubydoc.info/gems/pico_phone-rails
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -95,6 +97,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: 'Rails integration for pico_phone: attribute type, validator, and normalizer
-  for phone numbers'
+summary: 'Rails integration for pico_phone: attribute type, validator, normalizer,
+  and ActiveJob serializer'
 test_files: []