pico_phone-rails 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a77136e5c4b12dd9a039e2fc5fb3a417bd6eae8e353c937f9c05b8c7b768fea4
-  data.tar.gz: 6979e2642a4793889171a5de42a7f5bf209b486a4845488fd296b8af54821425
+  metadata.gz: a727b58fa9b03d91f9fed795d5f9b4898c8b6c1d416fa67eed38dc881c8a738a
+  data.tar.gz: 2727b559da6ec1a963f6b12f032aeeb9458eaacb5522e3ee98aabbb289863c28
 SHA512:
-  metadata.gz: 8ee3cebc17f0fa5fa98ad427b763b024ad97114738d40e774739a50c04abe2c5c9082177fdefb31bd6e9a1a89ef9d026da6c1a0a7aafbca5c1c30473dd456366
-  data.tar.gz: dffc493a5abe2b513629b9fa29cc7ac741d5181f7e128add7d592baeab92e4b3c757f3e9d5ecc2faf82067b76810498f681b15a5d0400dde53e5cd5e0d53d809
+  metadata.gz: f07be21c54bcd8f6f9f054af69875b7993f4428f6ef57a97d57252fcee3b71f540b1bcae6563568823c98960e4894afded9ec2e243178af10c36ff2a3dccca1d
+  data.tar.gz: 5b409b31ddbeaae09328eb1cbf6a98d392ad9cce01d5e047198c96149c6e985b9125baaa02c3557decbd1baacb6fc55e492203f9b9a76becd9386162474bad79

data/README.md

@@ -1,8 +1,8 @@
 # pico_phone-rails
 
 Rails integration for [`pico_phone`](https://github.com/gjack/pico_phone): an
-ActiveRecord attribute type, an ActiveModel validator, and a before-validation
-normalizer for phone numbers.
+ActiveRecord attribute type, an ActiveModel validator, a before-validation
+normalizer, and an ActiveJob serializer for phone numbers.
 
 ## Installation
 
@@ -52,6 +52,17 @@ A `before_validation` callback that rewrites the column to E.164 when it parses
 as valid, so formatting noise ("(510) 274-5656") is stripped before the
 validator runs. Pairs naturally with the validator above.
 
+### ActiveJob serializer
+
+```ruby
+MyJob.perform_later(phone: PicoPhone.parse("+15102745656", "US"))
+```
+
+A `PicoPhone::PhoneNumber` passed as a job argument survives the round trip
+through your queue backend (Sidekiq, Solid Queue, GoodJob, etc.) without
+manually converting to/from a string — `perform` receives back a real
+`PhoneNumber`, not the E.164 string it was serialized as.
+
 ## Development
 
 ```bash
@@ -67,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/railtie.rb

@@ -17,6 +17,13 @@ module PicoPhone
         end
       end
 
+      initializer "pico_phone_rails.active_job_serializer" do
+        ActiveSupport.on_load(:active_job) do
+          require "pico_phone/rails/serializers/phone_number_serializer"
+          ActiveJob::Serializers.add_serializers(PicoPhone::Rails::Serializers::PhoneNumberSerializer)
+        end
+      end
+
       initializer "pico_phone_rails.i18n" do |app|
         app.config.i18n.load_path += Dir[File.expand_path("locale/*.yml", __dir__)]
       end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module PicoPhone
+  module Rails
+    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.
+      #
+      # #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
+
+        # 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
+      end
+    end
+  end
+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.1.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.1.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: []
@@ -67,6 +68,7 @@ files:
 - lib/pico_phone/rails/locale/en.yml
 - lib/pico_phone/rails/normalizer.rb
 - lib/pico_phone/rails/railtie.rb
+- lib/pico_phone/rails/serializers/phone_number_serializer.rb
 - lib/pico_phone/rails/type.rb
 - lib/pico_phone/rails/version.rb
 homepage: https://github.com/gjack/pico_phone-rails
@@ -77,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:
@@ -94,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: []