serialize_attributes 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 809e8a18bc0152b6f9961215ee10b10769b90c01e7973e094ea238e09e4bacc5
-  data.tar.gz: fa5e51462f9e9f7a57048dec29c6d09ec041dd1a748242674f6560956c4c91a7
+  metadata.gz: f4fa19f41c2a597b312db2432d1df9a2efad508c91feebd885caab60f68304ac
+  data.tar.gz: a84b9c79d3bc59c8a416d8c2c3f2f08f46bdf3a25d8de465c8fb61593ce181aa
 SHA512:
-  metadata.gz: 5ab61e0943e013c453cec02210764f1dab818e640185c416564b19d4f3e62c85993068e7cb68b1cb268205f42086f8fc65de318aa07c3bdf620dfdf4ea4e6c56
-  data.tar.gz: 60ac9d6688461a364c81bef28a79b4e03707c00ae20e05b3d5dbbc40a63d93a64e646f73c44a8315ff3aa87b151c710754ed7fede08162b58438e2981257027c
+  metadata.gz: c5f6f45154a0b8f28b8712f81714c4d4eccccb9a58b7a54a0d2fe24499c101656d6416d80cf34eac0632de6444b8fe0b57503cbec6a5a2f8ffdea21badd7428c
+  data.tar.gz: 336dfe149b07fb43a171d417a79d33f1fc67eec5d6399cb73a803f38f0fc2afa72cafd1da859c489ad1c92551291337599dfb55827678f46c6717845288fc273

data/README.md

@@ -7,7 +7,7 @@ class MyModel
   serialize_attributes :settings do
     attribute :user_name, :string
     attribute :subscribed, :boolean, default: false
-    attribute :subscriptions, :string, array: true 
+    attribute :subscriptions, :string, array: true
   end
 end
 ```
@@ -145,6 +145,54 @@ specify a `default` attribute yourself explicitly:
 attribute :emails, :string, array: true, default: ["unknown@example.com"]
 ```
 
+### Enumerated ("enum") types
+
+Since enum types are a common thing when managing external data, there is a special enum
+type defined by the library:
+
+```ruby
+class MyModel
+  serialize_attributes :settings do
+    attribute :state, :enum, of: ["open", "closed"]
+  end
+end
+```
+
+Unlike `ActiveRecord::Enum`, enums here work by attaching an inclusion validator to your
+model. So for example, with the above code, I'll get a validation failure by default:
+
+```ruby
+MyModel.new(state: nil).tap(&:valid?).errors
+#=> { state: "is not included in the list" }
+```
+
+If you wish to allow nil values in your enum, you should add it to the `of` collection:
+
+```ruby
+attribute :state, :enum, of: [nil, "open", "closed"]
+```
+
+The column is probably now the source of truth for correct values, so you can also
+introspect the store to fetch these from elsewhere (e.g. for building documentation):
+
+```ruby
+MyModel.serialized_attributes_store(:settings).enum_options(:state)
+#=> ["open", "closed"]
+```
+
+Finally, you can also use complex types within the enum itself, by passing an additional
+`type:` attribute. Values will then be cast or deserialized per that type, and the result
+of the casting is what is validated, e.g:
+
+```ruby
+attribute :state, :enum, of: [nil, true, false], type: :boolean
+```
+
+```ruby
+MyModel.new(state: "f").state
+#=> false
+```
+
 ### Usage with ActiveModel alone
 
 It's also possible to use this library without `ActiveRecord`:

data/lib/serialize_attributes/store.rb

@@ -19,16 +19,16 @@ module SerializeAttributes
     # Get a list of the attributes managed by this store. Pass an optional `type` argument
     # to filter attributes by their type.
     #
-    #   Model.serialize_attributes_store(:settings).attribute_names
+    #   Model.serialized_attributes_store(:settings).attribute_names
     #   => [:user_name, :subscribed, :subscriptions]
     #
-    #   Model.serialize_attributes_store(:settings).attribute_names(type: :string)
+    #   Model.serialized_attributes_store(:settings).attribute_names(type: :string)
     #   => [:user_name, :subscriptions]
     #
-    #  Model.serialize_attributes_store(:settings).attribute_names(type: :string, array: true)
+    #  Model.serialized_attributes_store(:settings).attribute_names(type: :string, array: true)
     #  => [:subscriptions]
     #
-    #  Model.serialize_attributes_store(:settings).attribute_names(type: :string, array: false)
+    #  Model.serialized_attributes_store(:settings).attribute_names(type: :string, array: false)
     #  => [:user_name]
     #
     #
@@ -42,6 +42,17 @@ module SerializeAttributes
       end.keys
     end
 
+    # Get a list of enumerated options for the column `name` in this store.
+    #
+    #   Model.serialized_attributes_store(:settings).enum_options(:enumy)
+    #   => [nil, "placed", "confirmed"]
+    def enum_options(name)
+      type = @attributes.fetch(name.to_sym)
+      raise ArgumentError, "`#{name}` attribute is not an enum type" unless type.respond_to?(:options)
+
+      type.options
+    end
+
     # Cast a stored attribute against a given name
     #
     #    Model.serialized_attributes_store(:settings).cast(:user_name, 42)
@@ -88,20 +99,28 @@ module SerializeAttributes
       end
     end
 
-    def attribute(name, type, **options)
+    NO_DEFAULT = Object.new
+
+    def attribute(name, type, default: NO_DEFAULT, array: false, **type_options)
       name = name.to_sym
-      arr = options.delete(:array) { false }
-      type = ActiveModel::Type.lookup(type, **options.except(:default)) if type.is_a?(Symbol)
-      type = ArrayWrapper.new(type) if arr
+      type = ActiveModel::Type.lookup(type, **type_options) if type.is_a?(Symbol)
+
+      if array
+        raise ArgumentError, "Enum-arrays not currently supported" if type.is_a?(Types::Enum)
+
+        type = ArrayWrapper.new(type)
+      end
 
       @attributes[name] = type
 
-      if options.key?(:default)
-        @defaults[name] = options[:default]
-      elsif arr
+      if default != NO_DEFAULT
+        @defaults[name] = default
+      elsif array
         @defaults[name] = []
       end
 
+      type.attach_validations_to(@model_class, name) if type.respond_to?(:attach_validations_to)
+
       @model_class.module_eval <<~RUBY, __FILE__, __LINE__ + 1
         def #{name}                                          # def user_name
           if @_bad_typcasting                                #   if @_bad_typcasting
@@ -129,7 +148,7 @@ module SerializeAttributes
             .cast(:#{name}, value)                           #     .cast(:user_name, value)
           store = public_send(:#{@column_name})              #   store = public_send(:settings)
                                                              #
-          if #{arr} && cast_value == ArrayWrapper::EMPTY     #   if arr && cast_value == ArrayWrapper::EMPTY
+          if #{array} && cast_value == ArrayWrapper::EMPTY   #   if array && cast_value == ArrayWrapper::EMPTY
             store.delete("#{name}")                          #     store.delete("user_name")
           else                                               #   else
             store.merge!("#{name}" => cast_value)            #     store.merge!("user_name" => cast_value)

data/lib/serialize_attributes/types/enum.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/delegation"
+
+module SerializeAttributes
+  module Types
+    # A custom type which can only hold one of a set of predetermined values.
+    class Enum
+      attr_reader :options
+
+      # Construct a type instance.
+      #
+      # @param of   [Array]  One or more possible values that this type can take
+      # @param type [Symbol] An optional ActiveModel::Type instance, or symbol, for
+      #                      casting/uncasting (only required if enum has non-primitive types)
+      #
+      # @example Required to be one of two values
+      #   attribute :state, :enum, of: ["placed", "confirmed"]
+      #
+      # @example Optionally allowing nil
+      #   attribute :folding, :enum, of: [nil, "top-fold", "bottom-fold"]
+      #
+      # @example Casting input/output using another type
+      #   attribute :loves_pizza, :enum, of: [true], type: :boolean
+      #   # object.loves_pizza = "t"
+      #   #=> true
+      def initialize(of: [], type: nil)
+        @options = of.freeze
+        @type    = resolve_type(type)
+      end
+
+      def attach_validations_to(object, field_name)
+        object.validates_inclusion_of(field_name, in: @options)
+      end
+
+      delegate_missing_to :@type
+
+      private
+
+      UNTYPED_TYPE = ActiveModel::Type::Value.new
+
+      def resolve_type(given)
+        case given
+        in Symbol then ActiveModel::Type.lookup(given)
+        in nil    then UNTYPED_TYPE
+        in _      then given
+        end
+      end
+    end
+  end
+end
+
+ActiveModel::Type.register(:enum, SerializeAttributes::Types::Enum)

data/lib/serialize_attributes/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SerializeAttributes
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/lib/serialize_attributes.rb

@@ -2,6 +2,7 @@
 
 require "serialize_attributes/version"
 require "serialize_attributes/store"
+require "serialize_attributes/types/enum"
 
 # Serialize ActiveModel attributes in JSON using type casting
 module SerializeAttributes

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: serialize_attributes
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Zaikio
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-07-13 00:00:00.000000000 Z
+date: 2022-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -36,6 +36,7 @@ files:
 - Rakefile
 - lib/serialize_attributes.rb
 - lib/serialize_attributes/store.rb
+- lib/serialize_attributes/types/enum.rb
 - lib/serialize_attributes/version.rb
 homepage: https://github.com/zaikio/serialize_attributes
 licenses: