unmagic-enum 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b6ca718c4633bd4b4416c9e5b4f835b04515982c718fe328944eaa8a3e35447
-  data.tar.gz: 47868614586456e22c218b68157898ca35f927141316e7a8499682f92b2e8768
+  metadata.gz: e68600515b09d6a74e37e5f192337e3de577f002995460d10f89e49faba5d952
+  data.tar.gz: ed2bbb98d79b193bd2008ef4f74b323b34b7da58e56830543c78e0690173e2f8
 SHA512:
-  metadata.gz: 9c13abf83c50bcb036ee3631de10d5ffb14fde58a78e154e4af60574c94d6af1ad89c3424b03f25fa332de852bbd9f7e1f6755cfa728d5378c86118a6ce05516
-  data.tar.gz: 4f564234de61c4d44c3fd425c29518c99f938f8e9adda553ea1930bbe0332055cec4bea52fb83d8f6ca6bd6ca0134bd426befed056ac7013afd697376a9cc174
+  metadata.gz: e0f659e46165feea78f11c05acd4350f6f4880ccb529a59ced02aa81ff0be583d706cfb540bc2227b0789790a83321516a4d8ed6f40e96513f4ab4461bde3854
+  data.tar.gz: 6b523a02f77243db8483308ce5e3ed5b8fcb14acbc3d3098f17b7d68c9594acd7c1231a6840f77dcaf6a3649ddfbe44863ab7d03dd84995d3329cbd2bcd7388e

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-08-27
+
+### Fixed
+- `ArrayColumnType#changed_in_place?` compared `ActiveSupport::JSON.encode`'s compact serialization against the database's raw text, so any formatting difference — PostgreSQL's `jsonb` prints `["a", "b"]` with a space after each comma — flagged every multi-element record as changed the moment it loaded (dirtying `changes`/`saved_changes` and rewriting the column on every save). It now compares the deserialized raw value against the cast value, which also stops a stored value the enum no longer recognises (dropped on read) from marking an unmutated record as changed.
+
+## [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 +43,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,82 @@ 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 what the raw database value reads as against the current
+        # value. Order is significant. Deliberately not a string comparison of
+        # serialized forms: the database's own text rendering of a JSON document
+        # (e.g. PostgreSQL jsonb prints `["a", "b"]` with spaces) never matches
+        # ActiveSupport::JSON.encode's compact form, which would flag every
+        # multi-element record as changed the moment it loads.
+        def changed_in_place?(raw_old_value, new_value)
+          deserialize(raw_old_value) != cast(new_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.1"
   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.1
 platform: ruby
 authors:
 - Keith Pitt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-08 00:00:00.000000000 Z
+date: 2026-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport