unmagic-enum 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b6ca718c4633bd4b4416c9e5b4f835b04515982c718fe328944eaa8a3e35447
-  data.tar.gz: 47868614586456e22c218b68157898ca35f927141316e7a8499682f92b2e8768
+  metadata.gz: ccf66f61ae488422b3d515b215511b3a0be62d10d72c56123a175ff779666782
+  data.tar.gz: 1ee14dcf4a39545056630e5793bc4928eb7096225c61c2eb8b3588a0c3067789
 SHA512:
-  metadata.gz: 9c13abf83c50bcb036ee3631de10d5ffb14fde58a78e154e4af60574c94d6af1ad89c3424b03f25fa332de852bbd9f7e1f6755cfa728d5378c86118a6ce05516
-  data.tar.gz: 4f564234de61c4d44c3fd425c29518c99f938f8e9adda553ea1930bbe0332055cec4bea52fb83d8f6ca6bd6ca0134bd426befed056ac7013afd697376a9cc174
+  metadata.gz: 8b5fe7f97a7ccecf276d2657af7c530f594fa64aef1eff9b0d38b05139cd050d62f7423944ba8e69baf42bd30e52504c4a40b05e1e0fb13caa17bf287c2c1fef
+  data.tar.gz: 442edaf6a0ed84cd1486cb5e297448d93726271b1c4452bfb0ca01443023f760983f438bd42be19e985a15e622f0e9050f80a9bae69b2b74527cbd174e11c3ef

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-12
+
+### Added
+- `column_type(array: true)` for columns holding multiple values of one enum as a JSON array (a `json`/`jsonb` column). Elements get the same treatment as a scalar `column_type`: cast to enum instances, validated eagerly on assignment (honouring `validate:`), serialized to database values. Blank elements are dropped on cast — so the blank entry a check-box collection's auxiliary hidden field submits never reaches the stored array — and unknown stored values are dropped on read.
+
 ## [0.2.0] - 2026-06-09
 
 ### Added
@@ -33,6 +38,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Rails presence support (`blank?`/`present?`) and JSON serialization (`as_json`)
 - Empty strings treated as `nil`
 
-[Unreleased]: https://github.com/unreasonable-magic/unmagic-enum/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/unreasonable-magic/unmagic-enum/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/unreasonable-magic/unmagic-enum/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/unreasonable-magic/unmagic-enum/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/unreasonable-magic/unmagic-enum/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/unreasonable-magic/unmagic-enum/releases/tag/v0.1.0

data/README.md

@@ -81,6 +81,33 @@ message.state               # => Message::State::SENT
 message.state.sent?         # => true
 ```
 
+### Multiple Values (JSON Array Columns)
+
+For a `json`/`jsonb` column holding several values of one enum, pass `array: true`:
+
+```ruby
+class Article < ApplicationRecord
+  class Topic < Unmagic::Enum
+    SCIENCE = new("science")
+    POLITICS = new("politics")
+    SPORT = new("sport")
+  end
+
+  attribute :topics, Topic.column_type(array: true)
+end
+
+article = Article.new(topics: ["science", "sport"])
+article.topics              # => [Article::Topic::SCIENCE, Article::Topic::SPORT]
+```
+
+Each element behaves like a scalar `column_type`: cast to an enum instance,
+validated eagerly on assignment (an unknown element raises, unless built with
+`validate: true`), and serialized to its database value. Blank elements are
+dropped on cast — so the blank entry a check-box collection's auxiliary hidden
+field submits never reaches the stored array — and stored values the enum no
+longer recognises are dropped on read. The attribute always reads as an array,
+never `nil`.
+
 ### Key/Value Separation
 
 Useful when database values differ from code identifiers:

data/lib/unmagic/enum/active_record_extensions.rb

@@ -71,13 +71,77 @@ module Unmagic
         end
       end
 
+      # A column that stores multiple values of one enum, as a JSON array of the
+      # enum's database values (a `json`/`jsonb` column). Each element gets the
+      # same treatment ColumnType gives a single value: cast to an enum
+      # instance, validated eagerly on assignment, serialized to its database
+      # value. Blank elements are dropped during cast — so the blank entry a
+      # check-box collection's auxiliary hidden field submits never reaches the
+      # stored array — and unknown stored values are dropped on read, so the
+      # attribute always reads as an array of valid enum instances (never nil).
+      class ArrayColumnType < ActiveRecord::Type::Value
+        def initialize(enum_class, validate: false)
+          @enum_class = enum_class
+          @element_type = ColumnType.new(enum_class, validate: validate)
+          super()
+        end
+
+        def type
+          :json
+        end
+
+        # Cast to an array of enum instances. A single value wraps into a
+        # one-element array; nil casts to []. Elements cast leniently like
+        # ColumnType#cast (blank or unknown resolves to nil) and are compacted
+        # away — eager rejection of unknowns happens in #assert_valid_value.
+        def cast(value)
+          Array(value).map { |element| @element_type.cast(element) }.compact
+        end
+
+        # Deserialize the database's JSON document. Lenient like
+        # ColumnType#deserialize: an element the enum no longer recognises is
+        # dropped rather than raising on read.
+        def deserialize(value)
+          return [] if value.nil? || value == ''
+
+          value = ActiveSupport::JSON.decode(value) if value.is_a?(::String)
+
+          Array(value).map { |element| @element_type.deserialize(element) }.compact
+        end
+
+        # Validate each element at assignment time, the way ColumnType does for
+        # a single value: blanks are allowed (they're dropped by #cast); an
+        # unknown element raises unless the type was built with validate: true.
+        def assert_valid_value(value)
+          Array(value).each { |element| @element_type.assert_valid_value(element) }
+        end
+
+        # Serialize to a JSON array of database values for storage.
+        def serialize(value)
+          return nil if value.nil?
+
+          ActiveSupport::JSON.encode(Array(value).map { |element| @element_type.serialize(element) })
+        end
+
+        # Detect in-place mutation (e.g. `record.statuses << Status::ACTIVE`)
+        # by comparing the serialized forms. Order is significant.
+        def changed_in_place?(raw_old_value, new_value)
+          serialize(new_value) != raw_old_value
+        end
+      end
+
       module ClassMethods
         # For ActiveRecord attribute type definition. `validate:` mirrors
         # ActiveRecord::Enum (default false = raise eagerly on an unknown value;
-        # true = let model validations handle it). Memoised per option value.
-        def column_type(validate: false)
-          (@column_types ||= {})[validate] ||=
+        # true = let model validations handle it). `array: true` returns a type
+        # for columns holding multiple values of the enum as a JSON array.
+        # Memoised per option set.
+        def column_type(validate: false, array: false)
+          (@column_types ||= {})[[validate, array]] ||= if array
+            Unmagic::Enum::ActiveRecordExtensions::ArrayColumnType.new(self, validate: validate)
+          else
             Unmagic::Enum::ActiveRecordExtensions::ColumnType.new(self, validate: validate)
+          end
         end
       end
 

data/lib/unmagic/enum/version.rb

@@ -3,6 +3,6 @@
 module Unmagic
   class Enum
     # Current version of the unmagic-enum gem
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unmagic-enum
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Keith Pitt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-08 00:00:00.000000000 Z
+date: 2026-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport